@a-t-h-i/bot-lobby 0.6.52 → 0.6.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.52",
+  "version": "0.6.54",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/prompts/expert.md

@@ -0,0 +1,17 @@
+# Expert Consult
+
+A worker agent on a software task is stuck on a hard step, or about to make
+a choice it is unsure of, and is asking you for advice. You are a stronger
+model than it is; it cannot see your reasoning, only your answer.
+
+- Read the code it points to (and whatever else you need) before you answer.
+  You can read and search the repository; you cannot change it.
+- Answer the question it asked, concretely: the cause, the approach, the exact
+  functions, files, lines and shapes to use. Show a short code sketch when it
+  saves the worker a wrong turn.
+- Stay inside the worker's brief. Do not widen the step, redesign the plan or
+  hand it new work; when the brief itself looks wrong, say so in one line and
+  advise how to report it.
+- When you are not sure, say what would settle it (a file to read, a command
+  to run) instead of guessing.
+- Keep it short: a few paragraphs at most, most useful thing first.

package/prompts/goal-check.md

@@ -0,0 +1,44 @@
+# Goal Check
+
+You are the last check before a task is called done. You have a clean
+context on purpose: you have not seen the plan's reasoning, the workers'
+reports or the QA rounds, only what the user asked for and what changed.
+
+Your one question: does the change do what the user asked? Not whether it
+follows the plan, not whether the code is elegant, not whether more tests
+would be nice. A plan can drift from the request, and agents can finish
+every step and still miss the point; you catch that.
+
+## How
+
+1. Split the request (and any amendments) into the concrete things the user
+   asked for, one line each. Leave out what they did not ask for.
+2. For each one, find where the change does it: read the diff, then open the
+   files it touches when the diff alone does not settle it. Cite `path:line`.
+3. A requirement is met when the code does it, not when a comment, a TODO or
+   a report says so. Something the user asked for that is missing,
+   half-done, stubbed or done differently from how they asked is a gap.
+4. Do not run the test suite or build: QA did. Read; run a single quick
+   command only when reading cannot settle a requirement.
+5. Do not modify anything.
+
+Be strict about what was asked and lenient about everything else. Style,
+naming, refactors, extra polish and test coverage are never gaps. When the
+request is vague about something, the change meets it if a reasonable
+reading of the request is met.
+
+## Output
+
+Reply in exactly this format:
+
+## Verdict
+MET or NOT MET
+
+## Requirements
+- <requirement, in the user's words> — met — <path:line or what shows it>
+- <requirement> — not met — <what is missing, and where you looked>
+
+## Gaps
+- <one line per unmet requirement: what the user asked for and what the change does instead>
+
+Write `- none` under Gaps when the verdict is MET.

package/prompts/master.md

@@ -275,8 +275,17 @@ Every delegation costs a full agent run, so keep the loop short:
 - When steps for different domains are independent, run them together with
   `implement` `assignments` (one entry per domain). Workers then share files
   through the file desk: they claim files, queue for busy ones, and hand them
-  over with notes. Keep assignments to distinct domains, and give them the
-  shared contract up front.
+  over with notes (or, with `parallelMode: worktrees`, each works in a
+  checkout of its own and the engine applies their changes back). Keep
+  assignments to distinct domains, and give them the shared contract up
+  front.
+- On the full workflow with QA on the roster, put QA's test writing in the
+  same batch as the build, briefed from the plan's contracts and acceptance
+  criteria: QA writes the tests while DESIGN and DEV build, instead of
+  starting only once the build is done. On the shared desk QA can run them as
+  pieces land (it follows `done` posts); in worktrees mode it cannot see the
+  others' changes until the batch merges, so the QA gate runs them. The gate
+  still runs once after the batch either way.
 - Scout only the domains the change touches, with pointed questions; skip
   scouting when you already have the context. Target-verify one claim instead
   of re-scouting.
@@ -288,6 +297,48 @@ Every delegation costs a full agent run, so keep the loop short:
   has not changed since: take it as fresh, and do not scout again for it.
 - Run the QA gate once, after the implementation steps are done, not after
   every step.
+
+## How many agents
+
+More agents only help when the work really divides. Parallel agents on work
+that is one sequence (each step needs the last one's result) do worse than one
+agent doing it in order, and every extra agent costs a full run.
+
+- **One worker** for a change in one domain, or any change whose steps build
+  on each other (a migration, then the code that uses it, then its callers).
+  Brief its consecutive steps in one `implement`.
+- **Two or three workers in one batch** only when their parts are independent
+  given a contract you state up front: DESIGN builds the page while DEV builds
+  the endpoint it calls, and QA writes the tests from the acceptance criteria.
+- **Workers' own children** (a worker splitting its step) only for wide,
+  mechanical, file-disjoint work inside one domain: the same change across
+  many files, several independent components.
+- **Scouts**: only the domains the change touches; none when you already know
+  the code. **Researcher**: only when a decision turns on outside facts.
+
+When unsure, use fewer agents with fuller briefs.
+
+## Agents talking to each other
+
+You stay the one who decides what gets done and when the task is done. The
+agents share facts without you:
+
+- **The task board.** Workers post `contract`, `decision`, `blocker`,
+  `question`, `done` and `note` entries; each role reads the kinds it follows,
+  and running peers hear contracts and blockers at once. New posts are listed
+  in each `implement` report. Read them: a `blocker` or `question` addressed
+  to no one is yours to settle, and a `contract` a worker set is what the
+  others now build against. When you settle a contract yourself, put it in
+  every brief that needs it, as before.
+- **Peer questions.** Workers in one batch can ask each other short questions
+  (`ask_peer`) instead of guessing. Questions only: they never assign each
+  other work.
+- **Expert advice.** DESIGN and DEV can ask a stronger model for advice on a
+  hard step (`ask_expert`), a couple of times per step.
+- **Files, not relays.** A long worker report is kept whole in the task's
+  `reports/` folder and the report gives its path; long findings go in the
+  task's `notes/` folder. Read the file when the detail matters rather than
+  asking for it again.
 - A report flagged as wrapped up early or timed out may be partial: check what
   is missing and delegate only the remainder.
 
@@ -438,6 +489,13 @@ breaks this task.
 
 ## Completion
 
+Before the task completes, the engine runs a **goal check**: one read-only
+agent with a clean context reads the change against the user's own request
+and amendments (not your plan) and lists any requirement it does not meet.
+Gaps refuse completion: delegate a fix step for each, then complete again;
+the next check reads the new change. When a gap is deliberate (the user agreed
+to leave it out), complete again with `reason` saying so, and tell the user.
+
 Only you declare completion, and only after requirements are satisfied,
 implementation is verified, required tests pass, the QA gate passes (on the
 fast track: QA has taken part when it is on the roster), critical blockers are

package/prompts/worker.md

@@ -92,6 +92,24 @@ repository at the same time, and files are checked out like physical documents:
 - Files you still hold are handed over automatically when you finish, so
   release them early whenever others are waiting.
 
+## Working with the others
+
+- **Task board.** When `post_board` is available, post what other agents
+  build against or must follow, the moment you settle it: a `contract` (a
+  route, payload shape, type, event name, file location), a `decision`, a
+  `blocker` on someone else's part, and `done` when a piece is finished and
+  testable. Exact facts, a line or two each; never progress chatter. Read the
+  board (`read_board`) before you build against another domain's part.
+- **Peers.** When `ask_peer` is available, ask the worker who owns a part a
+  short question instead of guessing a name or a shape; answer theirs with
+  `answer_peer` straight away. Nobody takes work from a peer: only from the
+  brief.
+- **Expert.** When `ask_expert` is available and you are stuck after a real
+  attempt, or unsure about a hard choice, ask it with what you tried and the
+  files involved. Use it for the hard part, not to think for you.
+- **Long findings** go in a file under the task's notes folder (your context
+  names it); give its path under Notes.
+
 ## Before handoff
 
 - Go through the brief's "Done when" list one criterion at a time and record

package/src/desk/board-client.ts

@@ -0,0 +1,65 @@
+/**
+ * The task board inside a worker's pi process: `post_board` adds a typed post
+ * (through the desk when one runs, so peers hear about contracts and
+ * blockers at once; straight to the board's file otherwise) and `read_board`
+ * reads what the task's agents posted, filtered to the reader's role.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createDeskClient, type DeskClient } from "./ipc.ts";
+import { appendPost, BOARD_ENV, filterPosts, formatPosts, isPostKind, POST_KINDS, readBoard, subscriptionFor, type PostKind } from "./board.ts";
+import { deskAddress } from "./client-extension.ts";
+
+function text(value: string) {
+  return { content: [{ type: "text" as const, text: value }], details: undefined };
+}
+
+export function registerBoardClient(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env, client?: DeskClient): void {
+  const path = env[BOARD_ENV];
+  if (!path) return;
+  const target = deskAddress(env);
+  const desk = client ?? (target ? createDeskClient(target.address, target.worker) : undefined);
+  // Posts and subscriptions follow the worker's domain; a desk id is only the fallback.
+  const self = env.BOT_LOBBY_BOARD_FROM ?? target?.worker ?? "worker";
+  if (desk) pi.on("session_shutdown", () => desk.close());
+
+  pi.registerTool({
+    name: "post_board",
+    label: "Post to the task board",
+    description:
+      "Post a short, typed entry on the task board that every agent on this task can read: `contract` (an interface others build against: a route, a payload shape, a type, an event name), `decision` (a choice others should follow), `blocker` (something stopping you that someone else must change), `question` (open, for the oracle), `done` (a piece is finished and ready to test), `note`. Contracts and blockers reach the other running workers at once. Post facts, not progress chatter.",
+    parameters: Type.Object({
+      kind: Type.Union(POST_KINDS.map((kind) => Type.Literal(kind))),
+      text: Type.String({ description: "The post: the exact facts, at most a short paragraph" }),
+      files: Type.Optional(Type.Array(Type.String(), { description: "Files the post is about" })),
+    }),
+    async execute(_id, params) {
+      if (desk) {
+        const answer = await desk.request({ op: "post", from: self, kind: params.kind, text: params.text, files: params.files ?? [] });
+        // Only a desk without the board, or one never reached, leaves the post to the file below; any other answer may follow a write.
+        if (answer.ok || !/^This task has no board\.$|^the file desk is unavailable$/.test(answer.text)) return text(answer.text);
+      }
+      try {
+        const post = appendPost(path, { from: self, kind: params.kind, text: params.text, ...(params.files ? { files: params.files } : {}) });
+        return text(`Posted #${post.seq}.`);
+      } catch (error) {
+        return text(`Not posted: ${(error as Error).message}`);
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "read_board",
+    label: "Read the task board",
+    description: "Read the task board. By default you see the kinds your role follows, newest last; pass kinds to see others, or after to see only posts newer than one you have read.",
+    parameters: Type.Object({
+      kinds: Type.Optional(Type.Array(Type.String(), { description: `Any of: ${POST_KINDS.join(", ")}` })),
+      after: Type.Optional(Type.Number({ description: "Only posts after this number" })),
+    }),
+    async execute(_id, params) {
+      const kinds: readonly PostKind[] = params.kinds?.filter(isPostKind).length ? params.kinds.filter(isPostKind) : subscriptionFor(self);
+      const posts = filterPosts(readBoard(path), { kinds, ...(params.after ? { after: params.after } : {}), limit: 50 });
+      return text(posts.length > 0 ? formatPosts(posts) : "Nothing on the board for those kinds yet.");
+    },
+  });
+}

package/src/desk/board.ts

@@ -0,0 +1,200 @@
+/**
+ * The task board: one append-only log per task where the agents working on
+ * it post short, typed entries (a contract they set, a decision, a blocker, a
+ * finished piece) and read what the others posted, without routing it through
+ * the oracle. Each role reads only the kinds it subscribes to, so the board
+ * stays a shared reference rather than a chat everyone has to follow.
+ *
+ * It lives in the task's directory as `board.jsonl`, so later steps, the QA
+ * gate and the oracle read the same record; a worker without a running desk
+ * (a single step) appends to the file directly.
+ */
+import { appendFileSync, mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export const POST_KINDS = ["contract", "decision", "blocker", "question", "done", "note"] as const;
+export type PostKind = (typeof POST_KINDS)[number];
+
+export function isPostKind(value: unknown): value is PostKind {
+  return typeof value === "string" && (POST_KINDS as readonly string[]).includes(value);
+}
+
+export interface BoardPost {
+  /** Order on the board, from 1. */
+  seq: number;
+  /** Who posted it: a domain (`backend`, `designer`, `qa`), a child run id, or `oracle`. */
+  from: string;
+  kind: PostKind;
+  text: string;
+  /** Repository files the post is about, when it names any. */
+  files?: string[];
+  at: string;
+}
+
+/** Env name that gives a worker process its task board's file. */
+export const BOARD_ENV = "BOT_LOBBY_BOARD";
+
+/** Tools every worker gets when its task has a board. */
+export const BOARD_TOOLS: readonly string[] = ["post_board", "read_board"];
+
+/**
+ * What each role reads by default. A builder needs the contracts and
+ * decisions it builds against and anything blocking; QA also follows what is
+ * done, so it can run its tests against finished pieces.
+ */
+export const SUBSCRIPTIONS: Readonly<Record<string, readonly PostKind[]>> = {
+  backend: ["contract", "decision", "blocker", "question"],
+  designer: ["contract", "decision", "blocker", "question"],
+  qa: ["contract", "decision", "blocker", "done"],
+  oracle: POST_KINDS,
+};
+
+const DEFAULT_SUBSCRIPTION: readonly PostKind[] = ["contract", "decision", "blocker"];
+
+/** Kinds a running peer is told about the moment they are posted, not only when it next reads. */
+export const PUSHED_KINDS: ReadonlySet<PostKind> = new Set(["contract", "blocker"]);
+
+export function subscriptionFor(reader: string): readonly PostKind[] {
+  return SUBSCRIPTIONS[reader] ?? DEFAULT_SUBSCRIPTION;
+}
+
+export const MAX_POST_CHARS = 1500;
+const MAX_FILES = 20;
+
+export function boardPath(taskDir: string): string {
+  return join(taskDir, "board.jsonl");
+}
+
+function clean(text: string, max: number): string {
+  const trimmed = text.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max - 1)}…` : trimmed;
+}
+
+function isPost(value: unknown): value is BoardPost {
+  if (!value || typeof value !== "object") return false;
+  const post = value as Partial<BoardPost>;
+  return typeof post.seq === "number" && typeof post.from === "string" && isPostKind(post.kind) && typeof post.text === "string" && typeof post.at === "string";
+}
+
+/** Every post on the board, oldest first; a missing board is empty and a torn line is skipped. */
+export function readBoard(path: string): BoardPost[] {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return [];
+  }
+  const posts: BoardPost[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const post: unknown = JSON.parse(line);
+      if (isPost(post)) posts.push(post);
+    } catch {
+      // A torn line (a crash mid-append) is skipped.
+    }
+  }
+  return posts;
+}
+
+export interface NewPost {
+  from: string;
+  kind: PostKind;
+  text: string;
+  files?: readonly string[];
+}
+
+/** Longest a board path in a post may be. */
+const MAX_FILE_CHARS = 300;
+/** How long a writer waits for another process's append, and when a lock is taken to be left behind. */
+const LOCK_WAIT_MS = 2000;
+const STALE_LOCK_MS = 10_000;
+
+function sleep(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Run `write` holding the board's lock (a directory beside it, made
+ * atomically), so posts from several processes get distinct sequence
+ * numbers. A lock left by a crashed writer is broken once stale; past the
+ * wait the post goes in anyway rather than being lost.
+ */
+function withLock<T>(path: string, write: () => T): T {
+  const lock = `${path}.lock`;
+  const until = Date.now() + LOCK_WAIT_MS;
+  let held = false;
+  while (!held) {
+    try {
+      mkdirSync(lock);
+      held = true;
+    } catch {
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > STALE_LOCK_MS) rmSync(lock, { recursive: true, force: true });
+      } catch {
+        // Released meanwhile.
+      }
+      if (Date.now() > until) break;
+      sleep(5);
+    }
+  }
+  try {
+    return write();
+  } finally {
+    if (held) rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/** Append a post and return it as stored. Throws on an empty text, so the caller can tell the agent. */
+export function appendPost(path: string, post: NewPost, now = new Date()): BoardPost {
+  const text = clean(post.text, MAX_POST_CHARS);
+  if (!text) throw new Error("a board post needs text");
+  const files = (post.files ?? []).map((file) => clean(file, MAX_FILE_CHARS)).filter(Boolean).slice(0, MAX_FILES);
+  mkdirSync(dirname(path), { recursive: true });
+  return withLock(path, () => {
+    const seq = (readBoard(path).at(-1)?.seq ?? 0) + 1;
+    const stored: BoardPost = { seq, from: post.from, kind: post.kind, text, ...(files.length > 0 ? { files } : {}), at: now.toISOString() };
+    appendFileSync(path, `${JSON.stringify(stored)}\n`, "utf8");
+    return stored;
+  });
+}
+
+export interface BoardFilter {
+  kinds?: readonly PostKind[];
+  /** Only posts after this sequence number. */
+  after?: number;
+  /** Leave out the reader's own posts. */
+  notFrom?: string;
+  /** The newest N that match. */
+  limit?: number;
+}
+
+export function filterPosts(posts: readonly BoardPost[], filter: BoardFilter): BoardPost[] {
+  const matching = posts.filter(
+    (post) => (!filter.kinds || filter.kinds.includes(post.kind)) && post.seq > (filter.after ?? 0) && post.from !== filter.notFrom,
+  );
+  return filter.limit && matching.length > filter.limit ? matching.slice(-filter.limit) : matching;
+}
+
+const NAMES: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA", oracle: "ORACLE" };
+
+export function posterName(from: string): string {
+  return NAMES[from] ?? (from.length > 12 ? `child ${from.slice(0, 8)}` : from.toUpperCase());
+}
+
+/** One post on one line: its text is flattened, so a post can never pass for a line of the engine's own. */
+export function formatPost(post: BoardPost): string {
+  const files = post.files?.length ? ` (${post.files.join(", ")})` : "";
+  return `#${post.seq} [${post.kind}] ${posterName(post.from)}${files}: ${post.text.replace(/\s+/g, " ")}`;
+}
+
+export function formatPosts(posts: readonly BoardPost[]): string {
+  return posts.map(formatPost).join("\n");
+}
+
+/** The board as a context section for an agent starting a step: what its role subscribes to, newest last. */
+export function boardContext(path: string, reader: string, limit = 30): string {
+  const posts = filterPosts(readBoard(path), { kinds: subscriptionFor(reader), limit });
+  if (posts.length === 0) return "";
+  return `Task board (what the task's agents posted for each other; ${subscriptionFor(reader).join(", ")} posts):\n${formatPosts(posts)}`;
+}

package/src/desk/client-extension.ts

@@ -7,7 +7,7 @@
 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";
+import { ASK_WAIT_MS, DESK_ENV, isEditTool, MAX_ASK_WAIT_MS, MAX_WAIT_MS } from "./session.ts";
 
 function text(value: string) {
   return { content: [{ type: "text" as const, text: value }], details: undefined };
@@ -98,4 +98,34 @@ export function registerDeskClient(pi: ExtensionAPI, client?: DeskClient): void
       return text((await desk.request({ op: "wait", timeoutMs }, timeoutMs + 5000)).text);
     },
   });
+
+  pi.registerTool({
+    name: "ask_peer",
+    label: "Ask a peer",
+    description:
+      "Ask another worker in this batch a short question about its part (a field name, a route, a shape it settled) and wait for its answer, instead of guessing. Name the peer (DEV, DESIGN or QA), or give a file path to ask whoever holds it. Questions only: peers cannot give each other work. Waits up to 90 seconds by default.",
+    parameters: Type.Object({
+      question: Type.String({ description: "The question, in one or two sentences" }),
+      to: Type.Optional(Type.String({ description: "DEV, DESIGN or QA" })),
+      path: Type.Optional(Type.String({ description: "Ask whoever holds this file instead" })),
+      seconds: Type.Optional(Type.Number({ description: "How long to wait, at most 180 seconds" })),
+    }),
+    async execute(_id, params) {
+      const timeoutMs = Math.min(MAX_ASK_WAIT_MS, Math.max(5, params.seconds ?? ASK_WAIT_MS / 1000) * 1000);
+      return text((await desk.request({ op: "ask", text: params.question, to: params.to ?? "", path: params.path ?? "", timeoutMs }, timeoutMs + 5000)).text);
+    },
+  });
+
+  pi.registerTool({
+    name: "answer_peer",
+    label: "Answer a peer",
+    description: "Answer a question another worker asked you (the desk tells you its id). Answer from what you know or have built, in a line or two, then carry on with your own work.",
+    parameters: Type.Object({
+      id: Type.Number({ description: "The question's id" }),
+      answer: Type.String({ description: "Your answer" }),
+    }),
+    async execute(_id, params) {
+      return text((await desk.request({ op: "answer", questionId: params.id, text: params.answer })).text);
+    },
+  });
 }

package/src/desk/ipc.ts

@@ -9,7 +9,7 @@ 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" | "delegate" | "cancel_delegate";
+export type DeskOp = "hello" | "check" | "claim" | "handover" | "mine" | "wait" | "delegate" | "cancel_delegate" | "consult" | "cancel_consult" | "post" | "ask" | "answer";
 
 export interface DeskRequest {
   id: number;
@@ -20,6 +20,17 @@ export interface DeskRequest {
   briefs?: string[];
   note?: string;
   timeoutMs?: number;
+  /** post: who posts (the worker's domain; its desk id otherwise), the post's kind and text, and the files it is about. */
+  from?: string;
+  kind?: string;
+  text?: string;
+  files?: string[];
+  /** ask: who the question is for (DEV, DESIGN, QA); `path` asks whoever holds that file. */
+  to?: string;
+  /** answer: the question being answered. */
+  questionId?: number;
+  /** An expert consult's own id, so the worker can cancel it. */
+  consultId?: string;
 }
 
 export interface DeskResponse {