@a-t-h-i/bot-lobby 0.2.0 → 0.4.0

package/prompts/worker.md

@@ -25,8 +25,41 @@ section of your output instead and continue with the rest of the work.
 
 ## Testing
 
-Run the project's existing test commands. New public behavior, endpoints, and
-bug fixes require appropriate tests before claiming completion.
+Run the targeted tests for what you changed (the files and behavior you
+touched); the QA gate runs the full suite afterwards. New public behavior,
+endpoints, and bug fixes require appropriate tests before claiming completion.
+
+- Always pass a bash `timeout` to tests and builds (for example 300 seconds).
+- Never start dev servers, watch mode or other long-running processes, and
+  never leave background processes behind.
+- Change files with `edit`/`write`, not through shell redirection or `sed -i`.
+
+## Time budget
+
+Work efficiently: read what you need, make the change, verify, report. If the
+engine asks you to wrap up, stop exploring, leave every file consistent, and
+write your report with anything unfinished under Blockers or Notes.
+
+## Working alongside other workers (file desk)
+
+When the `claim_file` tool is available, other workers are editing the same
+repository at the same time, and files are checked out like physical documents:
+
+- Before editing or writing a file, call `claim_file` with the path and a
+  one-line intent (what you are about to do to it). Reading never needs a claim.
+- If another worker holds the file, you are queued: keep working on your other
+  files instead of waiting. You will be told when it is handed to you, together
+  with the previous holder's notes; re-read the file before editing it.
+- You are always told who is queued behind you on files you hold, and what they
+  intend to do. As soon as you are finished with a file, call `handover_file`
+  with a short note written for the next worker's intent: what you changed,
+  what they should build on, and what to watch out for. The desk hands it to
+  whoever is next.
+- Use `my_files` to see what you hold, what you are waiting for, and each
+  queue. Use `wait_for_files` only when nothing else is left to do, and hand
+  over every file someone is waiting for first.
+- Files you still hold are handed over automatically when you finish, so
+  release them early whenever others are waiting.
 
 ## Before handoff
 

package/src/desk/client-extension.ts

@@ -0,0 +1,101 @@
+/**
+ * The file desk inside a parallel worker's pi process. Registered only when
+ * bot-lobby runs as a subagent with a desk address in its environment: it
+ * refuses `edit`/`write` on files the worker has not checked out, and gives
+ * the worker the tools to claim, hand over and wait for files.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createDeskClient, type DeskClient } from "./ipc.ts";
+import { DESK_ENV, isEditTool, MAX_WAIT_MS } from "./session.ts";
+
+function text(value: string) {
+  return { content: [{ type: "text" as const, text: value }], details: undefined };
+}
+
+function editPath(input: unknown): string | undefined {
+  if (!input || typeof input !== "object") return undefined;
+  const record = input as Record<string, unknown>;
+  const path = record.path ?? record.file_path;
+  return typeof path === "string" ? path : undefined;
+}
+
+/** True when this process is a worker in a parallel batch. */
+export function deskAddress(env: NodeJS.ProcessEnv = process.env): { address: string; worker: string } | undefined {
+  const address = env[DESK_ENV.address];
+  const worker = env[DESK_ENV.worker];
+  return address && worker ? { address, worker } : undefined;
+}
+
+export function registerDeskClient(pi: ExtensionAPI, client?: DeskClient): void {
+  const target = deskAddress();
+  if (!target && !client) return;
+  const desk = client ?? createDeskClient(target!.address, target!.worker);
+
+  pi.on("session_start", () => {
+    void desk.request({ op: "hello" });
+  });
+  pi.on("session_shutdown", () => desk.close());
+
+  pi.on("tool_call", async (event) => {
+    if (!isEditTool(event.toolName)) return undefined;
+    const path = editPath(event.input);
+    if (!path) return undefined;
+    const answer = await desk.request({ op: "check", path });
+    // If the desk is gone the batch is over; never wedge the worker on it.
+    if (!answer.ok || answer.allowed) return undefined;
+    return { block: true, reason: answer.text };
+  });
+
+  pi.registerTool({
+    name: "claim_file",
+    label: "Claim file",
+    description:
+      "Check a repository file out from the file desk before editing it. Give the path and a one-line intent (what you are about to change). A free file is yours at once; a busy one queues you behind its holder, who is told your intent.",
+    parameters: Type.Object({
+      path: Type.String({ description: "File path, relative to the repository root" }),
+      intent: Type.String({ description: "One line: what you will change in this file" }),
+    }),
+    async execute(_id, params) {
+      return text((await desk.request({ op: "claim", path: params.path, intent: params.intent })).text);
+    },
+  });
+
+  pi.registerTool({
+    name: "handover_file",
+    label: "Hand over file",
+    description:
+      "Release a file you hold to the next worker in its queue. Write the note for their stated intent: what you changed, what to build on, and what to watch out for.",
+    parameters: Type.Object({
+      path: Type.String({ description: "File path you hold" }),
+      note: Type.String({ description: "Handover note for the next worker" }),
+    }),
+    async execute(_id, params) {
+      return text((await desk.request({ op: "handover", path: params.path, note: params.note })).text);
+    },
+  });
+
+  pi.registerTool({
+    name: "my_files",
+    label: "My files",
+    description: "List the files you hold (with who is queued behind you and why) and the files you are queued for.",
+    parameters: Type.Object({}),
+    async execute() {
+      return text((await desk.request({ op: "mine" })).text);
+    },
+  });
+
+  pi.registerTool({
+    name: "wait_for_files",
+    label: "Wait for files",
+    description:
+      "Wait until a file you are queued for is handed to you (up to 2 minutes). Use only when nothing else is left to do; hand over files others wait for first.",
+    parameters: Type.Object({
+      seconds: Type.Optional(Type.Number({ description: "How long to wait, at most 120 seconds" })),
+    }),
+    async execute(_id, params) {
+      const timeoutMs = Math.min(MAX_WAIT_MS, Math.max(1, params.seconds ?? 120) * 1000);
+      return text((await desk.request({ op: "wait", timeoutMs }, timeoutMs + 5000)).text);
+    },
+  });
+}

package/src/desk/desk.ts

@@ -0,0 +1,249 @@
+/**
+ * The file desk: checkout and handover of repository files between workers
+ * that run in parallel, the way people share a physical document.
+ *
+ * A worker claims a file with a one-line intent before editing it. A free
+ * file is granted at once; a held file queues the claimant behind the holder,
+ * and the holder is told who is waiting and what they intend. When the holder
+ * hands the file over (with a note written for the next worker's intent), or
+ * finishes, the file passes to the head of the queue together with that note.
+ * Reads never need a claim. Everything lives in the master process, so a
+ * crashed worker can never leave a stale lock behind.
+ */
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type WorkerId = string;
+
+export interface Claim {
+  worker: WorkerId;
+  intent: string;
+}
+
+/** One file's checkout state as a worker sees it. */
+export interface FileView {
+  path: string;
+  holder: Claim;
+  queue: Claim[];
+}
+
+export interface Handover {
+  path: string;
+  from: WorkerId;
+  to: WorkerId;
+  note: string;
+  auto: boolean;
+  at: number;
+}
+
+export type ClaimResult =
+  | { status: "granted"; path: string; queue: Claim[] }
+  | { status: "held"; path: string; queue: Claim[] }
+  | { status: "queued"; path: string; holder: Claim; position: number };
+
+export type HandoverResult =
+  | { ok: true; path: string; to?: Claim; queue: Claim[] }
+  | { ok: false; path: string; error: string };
+
+/** What the desk tells workers; the session turns these into steering messages. */
+export type DeskEvent =
+  /** `to` holds `path` and its queue changed (someone joined or left). */
+  | { type: "queue"; to: WorkerId; path: string; queue: Claim[] }
+  /** `to` now holds `path`, handed over by `from` with `note`; `queue` is who waits behind it. */
+  | { type: "granted"; to: WorkerId; path: string; from: WorkerId; note: string; intent: string; queue: Claim[] }
+  /** `worker` joined the queue for `path` behind `holder`. */
+  | { type: "queued"; worker: WorkerId; path: string; holder: WorkerId; position: number };
+
+interface Entry {
+  holder: Claim;
+  queue: Claim[];
+}
+
+interface Waiter {
+  resolve: (grants: DeskEvent[]) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const MAX_INTENT = 160;
+const MAX_NOTE = 1200;
+
+function clean(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+export class FileDesk {
+  private readonly files = new Map<string, Entry>();
+  private readonly waiters = new Map<WorkerId, Waiter>();
+  private readonly pendingGrants = new Map<WorkerId, DeskEvent[]>();
+  private readonly log: Handover[] = [];
+  private readonly cwd: string;
+  private readonly onEvent: (event: DeskEvent) => void;
+  private readonly now: () => number;
+
+  constructor(cwd: string, onEvent: (event: DeskEvent) => void = () => {}, now: () => number = Date.now) {
+    this.cwd = resolve(cwd);
+    this.onEvent = onEvent;
+    this.now = now;
+  }
+
+  /** A stable key and display path for a file, relative to the repository root. */
+  normalize(path: string): string {
+    const absolute = isAbsolute(path) ? resolve(path) : resolve(this.cwd, path);
+    const rel = relative(this.cwd, absolute);
+    const display = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : absolute;
+    return display.replace(/\\/g, "/");
+  }
+
+  /** Claim `path` for `worker` with a short intent; grants a free file, queues behind a holder. */
+  claim(worker: WorkerId, path: string, intent: string): ClaimResult {
+    const key = this.normalize(path);
+    const claim = { worker, intent: clean(intent || "edit", MAX_INTENT) };
+    const entry = this.files.get(key);
+    if (!entry) {
+      this.files.set(key, { holder: claim, queue: [] });
+      return { status: "granted", path: key, queue: [] };
+    }
+    if (entry.holder.worker === worker) {
+      entry.holder = claim;
+      return { status: "held", path: key, queue: [...entry.queue] };
+    }
+    const existing = entry.queue.findIndex((queued) => queued.worker === worker);
+    if (existing >= 0) entry.queue[existing] = claim;
+    else entry.queue.push(claim);
+    const position = entry.queue.findIndex((queued) => queued.worker === worker) + 1;
+    if (existing < 0) {
+      this.onEvent({ type: "queued", worker, path: key, holder: entry.holder.worker, position });
+      this.onEvent({ type: "queue", to: entry.holder.worker, path: key, queue: [...entry.queue] });
+    }
+    return { status: "queued", path: key, holder: entry.holder, position };
+  }
+
+  /** True when `worker` currently holds `path`. */
+  holds(worker: WorkerId, path: string): boolean {
+    return this.files.get(this.normalize(path))?.holder.worker === worker;
+  }
+
+  /** Who holds `path`, if anyone. */
+  holderOf(path: string): Claim | undefined {
+    return this.files.get(this.normalize(path))?.holder;
+  }
+
+  /** Hand `path` to whoever is next in its queue, with a note for them; free it when nobody waits. */
+  handover(worker: WorkerId, path: string, note: string): HandoverResult {
+    const key = this.normalize(path);
+    const entry = this.files.get(key);
+    if (!entry || entry.holder.worker !== worker) {
+      return { ok: false, path: key, error: `you do not hold ${key}${entry ? ` (${entry.holder.worker} does)` : ""}` };
+    }
+    const next = this.pass(key, entry, worker, clean(note || "no note", MAX_NOTE), false);
+    return { ok: true, path: key, ...(next ? { to: next } : {}), queue: [...(this.files.get(key)?.queue ?? [])] };
+  }
+
+  /**
+   * Release everything `worker` holds (handing each file to its next worker
+   * with `note(path, next)`) and drop it from every queue. Used when a worker
+   * finishes, crashes or retries.
+   */
+  release(worker: WorkerId, note: (path: string, next: Claim) => string): Handover[] {
+    const passed: Handover[] = [];
+    for (const [key, entry] of [...this.files]) {
+      const before = entry.queue.length;
+      entry.queue = entry.queue.filter((queued) => queued.worker !== worker);
+      if (entry.holder.worker === worker) {
+        const head = entry.queue[0];
+        const next = this.pass(key, entry, worker, head ? clean(note(key, head), MAX_NOTE) : "", true);
+        if (next) passed.push(this.log.at(-1)!);
+      } else if (entry.queue.length !== before) {
+        this.onEvent({ type: "queue", to: entry.holder.worker, path: key, queue: [...entry.queue] });
+      }
+    }
+    const waiter = this.waiters.get(worker);
+    if (waiter) {
+      clearTimeout(waiter.timer);
+      this.waiters.delete(worker);
+      waiter.resolve([]);
+    }
+    this.pendingGrants.delete(worker);
+    return passed;
+  }
+
+  private pass(key: string, entry: Entry, from: WorkerId, note: string, auto: boolean): Claim | undefined {
+    const next = entry.queue.shift();
+    if (!next) {
+      this.files.delete(key);
+      return undefined;
+    }
+    entry.holder = next;
+    this.log.push({ path: key, from, to: next.worker, note, auto, at: this.now() });
+    const event: DeskEvent = { type: "granted", to: next.worker, path: key, from, note, intent: next.intent, queue: [...entry.queue] };
+    this.onEvent(event);
+    this.deliver(next.worker, event);
+    return next;
+  }
+
+  /** Wake a worker blocked in `wait` with its grant, or keep it for its next wait. */
+  private deliver(worker: WorkerId, event: DeskEvent): void {
+    const waiter = this.waiters.get(worker);
+    if (waiter) {
+      clearTimeout(waiter.timer);
+      this.waiters.delete(worker);
+      waiter.resolve([event]);
+      return;
+    }
+    this.pendingGrants.set(worker, [...(this.pendingGrants.get(worker) ?? []), event]);
+  }
+
+  /** Files `worker` holds that someone is waiting for; it must hand these over before it may wait. */
+  owed(worker: WorkerId): FileView[] {
+    return this.heldBy(worker).filter((file) => file.queue.length > 0);
+  }
+
+  heldBy(worker: WorkerId): FileView[] {
+    return [...this.files].filter(([, entry]) => entry.holder.worker === worker).map(([path, entry]) => ({ path, holder: entry.holder, queue: [...entry.queue] }));
+  }
+
+  /** Files `worker` is queued for, with its position. */
+  waitingFor(worker: WorkerId): Array<{ path: string; holder: Claim; position: number }> {
+    return [...this.files].flatMap(([path, entry]) => {
+      const index = entry.queue.findIndex((queued) => queued.worker === worker);
+      return index >= 0 ? [{ path, holder: entry.holder, position: index + 1 }] : [];
+    });
+  }
+
+  /**
+   * Wait up to `timeoutMs` for a file to be handed to `worker`. Refuses while
+   * the worker holds files others are waiting for, which breaks deadlock
+   * cycles: whoever waits first hands over first.
+   */
+  wait(worker: WorkerId, timeoutMs: number): Promise<{ refused?: FileView[]; grants: DeskEvent[] }> {
+    const owed = this.owed(worker);
+    if (owed.length > 0) return Promise.resolve({ refused: owed, grants: [] });
+    const pending = this.pendingGrants.get(worker);
+    if (pending?.length) {
+      this.pendingGrants.delete(worker);
+      return Promise.resolve({ grants: pending });
+    }
+    if (this.waitingFor(worker).length === 0) return Promise.resolve({ grants: [] });
+    return new Promise((done) => {
+      const timer = setTimeout(() => {
+        this.waiters.delete(worker);
+        done({ grants: [] });
+      }, Math.max(0, timeoutMs));
+      this.waiters.set(worker, { resolve: (grants) => done({ grants }), timer });
+    });
+  }
+
+  /** Every handover so far, oldest first. */
+  handovers(): Handover[] {
+    return [...this.log];
+  }
+
+  /** Wake every waiter; called when the batch ends. */
+  close(): void {
+    for (const [worker, waiter] of this.waiters) {
+      clearTimeout(waiter.timer);
+      waiter.resolve([]);
+      this.waiters.delete(worker);
+    }
+  }
+}

package/src/desk/ipc.ts

@@ -0,0 +1,178 @@
+/**
+ * Transport between the file desk (master process) and the workers' pi
+ * processes: newline-delimited JSON requests and responses over a private
+ * Unix socket (a named pipe on Windows). One server per parallel batch.
+ */
+import { randomBytes } from "node:crypto";
+import { chmodSync, rmSync } from "node:fs";
+import { createConnection, createServer, type Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export type DeskOp = "hello" | "check" | "claim" | "handover" | "mine" | "wait";
+
+export interface DeskRequest {
+  id: number;
+  worker: string;
+  op: DeskOp;
+  path?: string;
+  intent?: string;
+  note?: string;
+  timeoutMs?: number;
+}
+
+export interface DeskResponse {
+  id: number;
+  ok: boolean;
+  /** Human-readable answer for the worker's tool result or block reason. */
+  text: string;
+  /** `check` only: whether the worker may edit the file. */
+  allowed?: boolean;
+}
+
+export type DeskHandler = (request: DeskRequest) => Promise<Omit<DeskResponse, "id">>;
+
+export interface DeskServer {
+  address: string;
+  close(): Promise<void>;
+}
+
+function socketAddress(): string {
+  const name = `bl-desk-${process.pid}-${randomBytes(4).toString("hex")}`;
+  return process.platform === "win32" ? `\\\\.\\pipe\\${name}` : join(tmpdir(), `${name}.sock`);
+}
+
+/** Split a byte stream into complete lines, keeping any partial tail. */
+function lineReader(onLine: (line: string) => void): (chunk: string) => void {
+  let buffer = "";
+  return (chunk) => {
+    buffer += chunk;
+    let at = buffer.indexOf("\n");
+    while (at >= 0) {
+      const line = buffer.slice(0, at).trim();
+      buffer = buffer.slice(at + 1);
+      if (line) onLine(line);
+      at = buffer.indexOf("\n");
+    }
+  };
+}
+
+function serve(socket: Socket, handler: DeskHandler): void {
+  socket.setEncoding("utf8");
+  socket.on("error", () => socket.destroy());
+  socket.on(
+    "data",
+    lineReader((line) => {
+      let request: DeskRequest;
+      try {
+        request = JSON.parse(line) as DeskRequest;
+      } catch {
+        return;
+      }
+      handler(request)
+        .catch((error: Error) => ({ ok: false, text: `desk error: ${error.message}` }))
+        .then((response) => {
+          if (!socket.destroyed) socket.write(`${JSON.stringify({ ...response, id: request.id })}\n`);
+        });
+    }),
+  );
+}
+
+/** Start a desk server on a fresh private socket. */
+export async function startDeskServer(handler: DeskHandler): Promise<DeskServer> {
+  const address = socketAddress();
+  const sockets = new Set<Socket>();
+  const server = createServer((socket) => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    serve(socket, handler);
+  });
+  await new Promise<void>((done, fail) => {
+    server.once("error", fail);
+    server.listen(address, () => done());
+  });
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(address, 0o600);
+    } catch {
+      // Best effort: the socket already lives in the private temp dir.
+    }
+  }
+  return {
+    address,
+    close: () =>
+      new Promise((done) => {
+        for (const socket of sockets) socket.destroy();
+        server.close(() => {
+          if (process.platform !== "win32") rmSync(address, { force: true });
+          done();
+        });
+      }),
+  };
+}
+
+export interface DeskClient {
+  request(request: Omit<DeskRequest, "id" | "worker">, timeoutMs?: number): Promise<DeskResponse>;
+  close(): void;
+}
+
+/** A persistent connection from one worker to the desk; requests fail (never hang) when it is gone. */
+export function createDeskClient(address: string, worker: string): DeskClient {
+  let socket: Socket | undefined;
+  let nextId = 1;
+  const pending = new Map<number, { done: (response: DeskResponse) => void; timer: ReturnType<typeof setTimeout> }>();
+  const failAll = (text: string) => {
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.done({ id, ok: false, text });
+    }
+    pending.clear();
+  };
+  const connect = (): Socket => {
+    if (socket && !socket.destroyed) return socket;
+    const next = createConnection(address);
+    next.setEncoding("utf8");
+    next.on(
+      "data",
+      lineReader((line) => {
+        let response: DeskResponse;
+        try {
+          response = JSON.parse(line) as DeskResponse;
+        } catch {
+          return;
+        }
+        const entry = pending.get(response.id);
+        if (!entry) return;
+        pending.delete(response.id);
+        clearTimeout(entry.timer);
+        entry.done(response);
+      }),
+    );
+    next.on("error", () => failAll("the file desk is unavailable"));
+    next.on("close", () => failAll("the file desk closed"));
+    next.unref();
+    socket = next;
+    return next;
+  };
+  return {
+    request(request, timeoutMs = 10_000) {
+      const id = nextId++;
+      return new Promise((done) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          done({ id, ok: false, text: "the file desk did not answer" });
+        }, timeoutMs);
+        pending.set(id, { done, timer });
+        try {
+          connect().write(`${JSON.stringify({ ...request, id, worker })}\n`);
+        } catch {
+          failAll("the file desk is unavailable");
+        }
+      });
+    },
+    close() {
+      socket?.destroy();
+      socket = undefined;
+    },
+  };
+}