@a-t-h-i/bot-lobby 0.6.0 → 0.6.1

package/src/pi/owner.ts

@@ -1,10 +1,11 @@
 /**
- * What a session does for the task it drives, on its own clock. Every few
- * seconds a session that owns a task (in the terminal or headless, started
- * from another window's lobby) passes on what other sessions left for its
- * oracle, plan comments and inbox messages, and in auto mode keeps the oracle
- * going whenever its turn ends before the task is done. Subagents never own
- * tasks, so none of this runs in them.
+ * What a session does on its own clock. Every few seconds a session (in the
+ * terminal or headless, started from another window's lobby) refreshes its
+ * heartbeat so other windows see it running, passes on what other sessions
+ * left for its oracle — plan comments, messages for its task or for the
+ * session itself — and in auto mode keeps the oracle going whenever its turn
+ * ends before the task is done. Subagents never own tasks or show up as
+ * sessions, so none of this runs in them.
  */
 import type { KeyId } from "@earendil-works/pi-tui";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -12,7 +13,8 @@ import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
 import { activeTask, loadTask } from "../state/persistence.ts";
 import { detectProjectRoot, loadConfig } from "../state/project.ts";
 import { commentMessage, markCommentsDelivered, readPlanComments, undeliveredComments } from "../state/comments.ts";
-import { inboxMessage, markInboxDelivered, readInbox } from "../state/inbox.ts";
+import { inboxMessage, markInboxDelivered, markSessionInboxDelivered, readInbox, readSessionInbox } from "../state/inbox.ts";
+import { removePresence, writePresence } from "../state/presence.ts";
 import { isAutoMode, setAutoMode } from "../state/auto.ts";
 import { isSubagentProcess } from "./quiet.ts";
 import { isMinimized } from "./ui.ts";
@@ -26,6 +28,7 @@ export const AUTO_KEY = "alt+g";
 
 export type OwnerEvent =
   | { kind: "comments" | "inbox"; taskId: string; count: number }
+  | { kind: "messages"; count: number }
   | { kind: "auto"; taskId: string; on: boolean }
   | { kind: "nudge"; taskId: string }
   | { kind: "stalled"; taskId: string };
@@ -33,6 +36,8 @@ export type OwnerEvent =
 interface Owner {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
+  /** The session this clock runs for, kept so its heartbeat can be removed after its context goes stale. */
+  sessionId: string;
   root: string;
   configDir: string;
   timer?: ReturnType<typeof setInterval>;
@@ -84,6 +89,40 @@ export function deliverInbox(): number {
   return fresh.length;
 }
 
+/** Pass messages other sessions left for this session itself (it may have no task) to its Master. */
+export function deliverSessionInbox(): number {
+  const state = owner;
+  if (!state) return 0;
+  const sessionId = state.ctx.sessionManager.getSessionId();
+  const fresh = readSessionInbox(state.root, state.configDir, sessionId).filter((message) => !message.delivered);
+  if (fresh.length === 0) return 0;
+  state.pi.sendUserMessage(inboxMessage(fresh), state.ctx.isIdle() ? undefined : { deliverAs: "steer" });
+  markSessionInboxDelivered(state.root, state.configDir, sessionId, fresh.map((message) => message.id));
+  listener?.({ kind: "messages", count: fresh.length });
+  return fresh.length;
+}
+
+/** Tell other windows this session is running: its name, file, task and process. */
+export function heartbeat(): void {
+  const state = owner;
+  if (!state) return;
+  const name = state.pi.getSessionName?.();
+  const sessionFile = state.ctx.sessionManager.getSessionFile?.();
+  const task = ownTask(state);
+  try {
+    writePresence(state.root, state.configDir, {
+      sessionId: state.ctx.sessionManager.getSessionId(),
+      pid: process.pid,
+      mode: state.ctx.mode ?? "tui",
+      ...(name ? { name } : {}),
+      ...(sessionFile ? { sessionFile } : {}),
+      ...(live(task) ? { taskId: task.id } : {}),
+    });
+  } catch {
+    // A read-only project only means other windows do not see this one.
+  }
+}
+
 /** What auto mode remembers between nudges: the task as it was, and how many nudges changed nothing. */
 export interface AutoTrack {
   fingerprint: string;
@@ -172,13 +211,22 @@ export function toggleOwnAuto(): string {
 
 /** One tick of the owner's clock. */
 export function ownerTick(): void {
+  heartbeat();
   deliverComments();
   deliverInbox();
+  deliverSessionInbox();
   driveAuto();
 }
 
 function stop(): void {
   if (owner?.timer) clearInterval(owner.timer);
+  if (owner) {
+    try {
+      removePresence(owner.root, owner.configDir, owner.sessionId);
+    } catch {
+      // The heartbeat goes stale on its own.
+    }
+  }
   owner = undefined;
 }
 
@@ -186,7 +234,8 @@ function stop(): void {
 export function startOwner(pi: ExtensionAPI, ctx: ExtensionContext, configDir: string, pollMs = OWNER_POLL_MS): void {
   stop();
   if (isSubagentProcess()) return;
-  owner = { pi, ctx, root: detectProjectRoot(ctx.cwd, configDir), configDir };
+  owner = { pi, ctx, sessionId: ctx.sessionManager.getSessionId(), root: detectProjectRoot(ctx.cwd, configDir), configDir };
+  heartbeat();
   if (pollMs > 0) {
     owner.timer = setInterval(() => ownerTick(), pollMs);
     owner.timer.unref?.();

package/src/schemas/task.ts

@@ -121,6 +121,8 @@ export interface Task {
   ownerSessionId?: string;
   /** The planned task (PLAN-…) whose plan the user agreed in the planning panel: its proposal needs no approval. */
   approvedPlan?: string;
+  /** When the task was archived from the lobby (it then lives under archive/tasks, out of every list). */
+  archivedAt?: string;
 }
 
 export function createTask(

package/src/state/archive.ts

@@ -0,0 +1,99 @@
+/**
+ * Archiving and deleting tasks from the lobby. An archived task moves, whole,
+ * out of the task tree to `archive/tasks/<id>` beside the knowledge archive:
+ * no list, widget or session sees it any more, and it can be restored as it
+ * was. Deleting removes a task's folder for good. A task still under way is
+ * abandoned before it is archived, so it never comes back half-driven.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { TERMINAL_STATES, type Task } from "../schemas/task.ts";
+import { taskDir, tasksRoot } from "../knowledge/paths.ts";
+import { transition } from "./task-state.ts";
+import { dataRoot, readDataRoots } from "./project.ts";
+
+export function archiveRoot(root: string, configDir: string): string {
+  return join(dataRoot(root, configDir), "archive", "tasks");
+}
+
+/** Task ids become folder names: only ever one plain path segment. */
+function checkId(taskId: string): string {
+  if (!/^[\w.-]+$/.test(taskId) || taskId === "." || taskId === "..") throw new Error(`not a task id: ${taskId}`);
+  return taskId;
+}
+
+function readAt(dir: string): Task | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dir, "state.json"), "utf8")) as Task;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeAt(dir: string, task: Task): void {
+  writeFileSync(join(dir, "state.json"), JSON.stringify(task, null, 2), "utf8");
+}
+
+/** Where a task on the list lives: the newest tree that has it (bot-lobby, then the pre-rename ones). */
+function liveDir(root: string, configDir: string, taskId: string): string | undefined {
+  return readDataRoots(root, configDir).map((dr) => taskDir(dr, taskId)).find((dir) => existsSync(join(dir, "state.json")));
+}
+
+function archivedDir(root: string, configDir: string, taskId: string): string {
+  return join(archiveRoot(root, configDir), checkId(taskId));
+}
+
+/** Archived tasks, most recently archived first. */
+export function listArchivedTasks(root: string, configDir: string): Task[] {
+  const dir = archiveRoot(root, configDir);
+  if (!existsSync(dir)) return [];
+  const tasks: Task[] = [];
+  for (const entry of readdirSync(dir)) {
+    const task = readAt(join(dir, entry));
+    if (task) tasks.push(task);
+  }
+  return tasks.sort((a, b) => (b.archivedAt ?? b.updatedAt).localeCompare(a.archivedAt ?? a.updatedAt));
+}
+
+/**
+ * Move a task out of every list into the archive; one still under way is
+ * abandoned first (and says so in its decisions). Returns the archived task.
+ */
+export function archiveTask(root: string, configDir: string, taskId: string, now = new Date()): Task {
+  const from = liveDir(root, configDir, checkId(taskId));
+  const task = from ? readAt(from) : undefined;
+  if (!from || !task) throw new Error(`no task ${taskId}`);
+  const to = archivedDir(root, configDir, taskId);
+  if (existsSync(to)) throw new Error(`${taskId} is already in the archive`);
+  const stamp = now.toISOString();
+  if (!TERMINAL_STATES.includes(task.state)) {
+    transition(task, "abandoned", stamp);
+    task.decisions.push({ domain: "master", text: "Abandoned when it was archived from the lobby.", createdAt: stamp });
+  }
+  task.archivedAt = stamp;
+  writeAt(from, task);
+  mkdirSync(dirname(to), { recursive: true });
+  renameSync(from, to);
+  return task;
+}
+
+/** Bring an archived task back to the lists, as it was when archived. */
+export function restoreTask(root: string, configDir: string, taskId: string): Task {
+  const from = archivedDir(root, configDir, taskId);
+  const task = readAt(from);
+  if (!task) throw new Error(`${taskId} is not in the archive`);
+  const to = taskDir(dataRoot(root, configDir), taskId);
+  if (existsSync(to)) throw new Error(`a task ${taskId} is already on the list`);
+  delete task.archivedAt;
+  writeAt(from, task);
+  mkdirSync(tasksRoot(dataRoot(root, configDir)), { recursive: true });
+  renameSync(from, to);
+  return task;
+}
+
+/** Remove a task for good: its folder, from the list or from the archive. */
+export function deleteTask(root: string, configDir: string, taskId: string, where: "list" | "archive" = "list"): void {
+  const dir = where === "archive" ? archivedDir(root, configDir, taskId) : liveDir(root, configDir, checkId(taskId));
+  if (!dir || !existsSync(dir)) throw new Error(where === "archive" ? `${taskId} is not in the archive` : `no task ${taskId}`);
+  rmSync(dir, { recursive: true, force: true });
+}

package/src/state/inbox.ts

@@ -1,17 +1,21 @@
 /**
- * The task inbox: messages for a task's oracle written from any pi session
- * (the lobby of another window talking to a task it does not drive). Like plan
- * comments they live beside the task as an append-only JSON-lines log, never
- * inside state.json, and the session that owns the task delivers them to its
- * Master and records the delivery.
+ * Inboxes: messages for another session's oracle written from any pi session
+ * (the lobby of another window talking to a session it does not drive). A
+ * task's inbox lives beside the task, so a message waits there until some
+ * session drives the task; a session's inbox lives beside its heartbeat, for
+ * a running session with no task. Like plan comments they are append-only
+ * JSON-lines logs, never inside state.json, and the session they are for
+ * delivers them to its Master and records the delivery.
  */
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { taskDirFor } from "./persistence.ts";
+import { presenceDir } from "./presence.ts";
 
 export interface InboxMessage {
   id: string;
-  taskId: string;
+  /** The task it was left for; absent for a session's own inbox. */
+  taskId?: string;
   text: string;
   createdAt: string;
   /** The pi session that wrote it. */
@@ -30,6 +34,10 @@ export function inboxPath(root: string, configDir: string, taskId: string): stri
   return join(taskDirFor(root, configDir, taskId), "inbox.jsonl");
 }
 
+export function sessionInboxPath(root: string, configDir: string, sessionId: string): string {
+  return join(presenceDir(root, configDir), `${sessionId.replace(/[^\w.-]/g, "_")}.inbox.jsonl`);
+}
+
 function append(path: string, event: InboxEvent): void {
   mkdirSync(dirname(path), { recursive: true });
   appendFileSync(path, `${JSON.stringify(event)}\n`, "utf8");
@@ -56,12 +64,11 @@ function readEvents(path: string): InboxEvent[] {
   return events;
 }
 
-/** The task's messages, oldest first, with whether each reached the oracle. */
-export function readInbox(root: string, configDir: string, taskId: string): InboxMessage[] {
+function readAt(path: string, taskId?: string): InboxMessage[] {
   const byId = new Map<string, InboxMessage>();
-  for (const event of readEvents(inboxPath(root, configDir, taskId))) {
+  for (const event of readEvents(path)) {
     if (event.kind === "message" && !byId.has(event.id)) {
-      byId.set(event.id, { id: event.id, taskId, text: event.text, createdAt: event.at, ...(event.by ? { by: event.by } : {}), delivered: false });
+      byId.set(event.id, { id: event.id, ...(taskId ? { taskId } : {}), text: event.text, createdAt: event.at, ...(event.by ? { by: event.by } : {}), delivered: false });
     } else if (event.kind === "delivered") {
       const message = byId.get(event.id);
       if (message) message.delivered = true;
@@ -70,17 +77,44 @@ export function readInbox(root: string, configDir: string, taskId: string): Inbo
   return [...byId.values()];
 }
 
-/** Leave a message for the task's oracle; returns it. */
-export function sendToInbox(root: string, configDir: string, taskId: string, text: string, by?: string, now = new Date()): InboxMessage {
+function sendAt(path: string, text: string, by: string | undefined, now: Date, taskId?: string): InboxMessage {
   const body = text.trim().slice(0, MAX_INBOX_CHARS);
   if (!body) throw new Error("a message needs some text");
   const id = `${now.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  append(inboxPath(root, configDir, taskId), { kind: "message", id, text: body, at: now.toISOString(), ...(by ? { by } : {}) });
-  return { id, taskId, text: body, createdAt: now.toISOString(), ...(by ? { by } : {}), delivered: false };
+  append(path, { kind: "message", id, text: body, at: now.toISOString(), ...(by ? { by } : {}) });
+  return { id, ...(taskId ? { taskId } : {}), text: body, createdAt: now.toISOString(), ...(by ? { by } : {}), delivered: false };
+}
+
+function markAt(path: string, ids: readonly string[], now: Date): void {
+  for (const id of ids) append(path, { kind: "delivered", id, at: now.toISOString() });
+}
+
+/** The task's messages, oldest first, with whether each reached the oracle. */
+export function readInbox(root: string, configDir: string, taskId: string): InboxMessage[] {
+  return readAt(inboxPath(root, configDir, taskId), taskId);
+}
+
+/** Leave a message for the task's oracle; returns it. */
+export function sendToInbox(root: string, configDir: string, taskId: string, text: string, by?: string, now = new Date()): InboxMessage {
+  return sendAt(inboxPath(root, configDir, taskId), text, by, now, taskId);
 }
 
 export function markInboxDelivered(root: string, configDir: string, taskId: string, ids: readonly string[], now = new Date()): void {
-  for (const id of ids) append(inboxPath(root, configDir, taskId), { kind: "delivered", id, at: now.toISOString() });
+  markAt(inboxPath(root, configDir, taskId), ids, now);
+}
+
+/** A running session's own messages (it has no task to hold them), oldest first. */
+export function readSessionInbox(root: string, configDir: string, sessionId: string): InboxMessage[] {
+  return readAt(sessionInboxPath(root, configDir, sessionId));
+}
+
+/** Leave a message for a running session's oracle; returns it. */
+export function sendToSession(root: string, configDir: string, sessionId: string, text: string, by?: string, now = new Date()): InboxMessage {
+  return sendAt(sessionInboxPath(root, configDir, sessionId), text, by, now);
+}
+
+export function markSessionInboxDelivered(root: string, configDir: string, sessionId: string, ids: readonly string[], now = new Date()): void {
+  markAt(sessionInboxPath(root, configDir, sessionId), ids, now);
 }
 
 /** The message the owning session sends its Master for undelivered inbox messages. */

package/src/state/presence.ts

@@ -0,0 +1,99 @@
+/**
+ * Which pi sessions are running in this project right now. Every interactive
+ * or headless session with bot-lobby loaded (never a subagent) keeps a small
+ * heartbeat file beside the tasks, refreshed on its owner clock and removed
+ * when it ends; the lobby reads them to list the live sessions it can view,
+ * message or switch to. A heartbeat older than a few beats, or from a process
+ * that is gone, does not count.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { dataRoot } from "./project.ts";
+
+export interface Presence {
+  sessionId: string;
+  pid: number;
+  /** The pi session's name (a task's title once it starts one). */
+  name?: string;
+  /** The saved session file, so another window can switch to it once it ends. */
+  sessionFile?: string;
+  /** The task it drives, if any. */
+  taskId?: string;
+  /** `tui` for a terminal, `rpc` for a session another window started in the background. */
+  mode: string;
+  updatedAt: string;
+}
+
+/** A heartbeat older than this means the session is gone (its owner clock ticks every few seconds). */
+export const PRESENCE_TTL_MS = 15_000;
+/** A heartbeat this old is removed even if its process still runs (it switched sessions without saying so). */
+const FORGET_MS = 10 * 60_000;
+
+export function presenceDir(root: string, configDir: string): string {
+  return join(dataRoot(root, configDir), "sessions");
+}
+
+/** Session ids become file names: keep them to safe characters. */
+function safeId(sessionId: string): string | undefined {
+  return /^[\w.-]+$/.test(sessionId) ? sessionId : undefined;
+}
+
+function presencePath(root: string, configDir: string, sessionId: string): string | undefined {
+  const id = safeId(sessionId);
+  return id ? join(presenceDir(root, configDir), `${id}.json`) : undefined;
+}
+
+/** Record (or refresh) this session's heartbeat; atomic, so readers never see half a file. */
+export function writePresence(root: string, configDir: string, presence: Omit<Presence, "updatedAt">, now = new Date()): void {
+  const path = presencePath(root, configDir, presence.sessionId);
+  if (!path) return;
+  mkdirSync(presenceDir(root, configDir), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ ...presence, updatedAt: now.toISOString() }), "utf8");
+  renameSync(tmp, path);
+}
+
+export function removePresence(root: string, configDir: string, sessionId: string): void {
+  const path = presencePath(root, configDir, sessionId);
+  if (path) rmSync(path, { force: true });
+}
+
+/** Whether a process is running: signal 0 checks without touching it (EPERM still means it exists). */
+export function processAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * The sessions running in this project, newest heartbeat first. Heartbeats
+ * of processes that are gone are removed; merely late ones are skipped.
+ */
+export function livePresence(root: string, configDir: string, now = Date.now(), alive: (pid: number) => boolean = processAlive): Presence[] {
+  const dir = presenceDir(root, configDir);
+  if (!existsSync(dir)) return [];
+  const live: Presence[] = [];
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json") || file.endsWith(".tmp")) continue;
+    let presence: Presence;
+    try {
+      presence = JSON.parse(readFileSync(join(dir, file), "utf8")) as Presence;
+    } catch {
+      continue;
+    }
+    if (typeof presence?.sessionId !== "string" || typeof presence.pid !== "number") continue;
+    const age = now - Date.parse(presence.updatedAt);
+    // Gone, or so long silent that its process has moved on to another session: clear it away.
+    if (!alive(presence.pid) || !(age < FORGET_MS)) {
+      rmSync(join(dir, file), { force: true });
+      continue;
+    }
+    if (age > PRESENCE_TTL_MS) continue;
+    live.push(presence);
+  }
+  return live.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}