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

package/src/desk/session.ts

@@ -0,0 +1,214 @@
+/**
+ * One parallel batch's file desk as the master sees it: the checkout table,
+ * the socket the workers talk to, and the messages that keep every worker
+ * informed. Queue changes and handovers reach the right worker as steering
+ * messages over its RPC stdin, and the zen panel sees who is waiting.
+ */
+import { basename } from "node:path";
+import type { AgentHandle } from "../execution/agent-runner.ts";
+import { FileDesk, type Claim, type DeskEvent, type FileView, type Handover, type WorkerId } from "./desk.ts";
+import { startDeskServer, type DeskRequest, type DeskResponse, type DeskServer } from "./ipc.ts";
+
+/** Tools the desk adds to every parallel worker's allowlist. */
+export const DESK_TOOLS: readonly string[] = ["claim_file", "handover_file", "my_files", "wait_for_files"];
+
+/** Env names the desk client extension reads inside a worker process. */
+export const DESK_ENV = { address: "BOT_LOBBY_DESK", worker: "BOT_LOBBY_DESK_ID" } as const;
+
+/** Longest a single `wait_for_files` call may block. */
+export const MAX_WAIT_MS = 120_000;
+
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+export function isEditTool(name: string): boolean {
+  return EDIT_TOOLS.has(name);
+}
+
+function label(worker: WorkerId): string {
+  const names: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };
+  return names[worker] ?? worker.toUpperCase();
+}
+
+function queueLines(queue: readonly Claim[]): string {
+  return queue.map((claim, index) => `${index + 1}) ${label(claim.worker)} — ${claim.intent}`).join("; ");
+}
+
+/** Steering text for a holder whose queue changed. */
+export function queueMessage(path: string, queue: readonly Claim[]): string {
+  if (queue.length === 0) return `bot-lobby desk: nobody is waiting for \`${path}\` any more.`;
+  const next = queue[0]!;
+  return [
+    `bot-lobby desk: queue for \`${path}\` (you hold it): ${queueLines(queue)}.`,
+    `As soon as you are done with it, call handover_file with a short note for ${label(next.worker)}, who wants to: ${next.intent}.`,
+  ].join(" ");
+}
+
+/** Steering text for a worker who just received a file. */
+export function grantMessage(event: Extract<DeskEvent, { type: "granted" }>): string {
+  const behind = event.queue.length > 0 ? ` Queued behind you: ${queueLines(event.queue)}; hand it over when you are done.` : "";
+  return `bot-lobby desk: \`${event.path}\` is yours now (for: ${event.intent}). ${label(event.from)}'s handover note: ${event.note || "none"}. Re-read the file before editing it.${behind}`;
+}
+
+function describeHeld(files: readonly FileView[]): string {
+  if (files.length === 0) return "You hold no files.";
+  return files
+    .map((file) => `You hold \`${file.path}\` (${file.holder.intent})${file.queue.length > 0 ? `; waiting: ${queueLines(file.queue)}` : "; nobody waiting"}.`)
+    .join("\n");
+}
+
+export interface DeskSessionOptions {
+  cwd: string;
+  /** A worker that finished without handing a file over leaves this note for the next worker. */
+  onHandover?: (handover: Handover) => void;
+}
+
+/** Master-side desk for one batch of parallel workers. */
+export class DeskSession {
+  readonly desk: FileDesk;
+  private server?: DeskServer;
+  private readonly handles = new Map<WorkerId, AgentHandle>();
+  private readonly greeted = new Set<WorkerId>();
+  private readonly options: DeskSessionOptions;
+
+  constructor(options: DeskSessionOptions) {
+    this.options = options;
+    this.desk = new FileDesk(options.cwd, (event) => this.onEvent(event));
+  }
+
+  async open(): Promise<void> {
+    this.server = await startDeskServer((request) => this.handle(request));
+  }
+
+  /** Environment that points one worker's pi process at this desk. */
+  env(worker: WorkerId): Record<string, string> {
+    if (!this.server) throw new Error("desk is not open");
+    return { [DESK_ENV.address]: this.server.address, [DESK_ENV.worker]: worker };
+  }
+
+  /** Remember the running attempt's handle so the desk can steer it. */
+  attach(worker: WorkerId, handle: AgentHandle): void {
+    this.handles.set(worker, handle);
+  }
+
+  /** True once the worker's desk extension has checked in. */
+  greetedBy(worker: WorkerId): boolean {
+    return this.greeted.has(worker);
+  }
+
+  /** End of one attempt: hand everything it held to whoever is next, with `note` for them. */
+  release(worker: WorkerId, note: (path: string, next: Claim) => string): void {
+    this.handles.get(worker)?.annotate({ waitingFor: undefined });
+    this.handles.delete(worker);
+    for (const handover of this.desk.release(worker, note)) this.options.onHandover?.(handover);
+  }
+
+  handovers(): Handover[] {
+    return this.desk.handovers();
+  }
+
+  async close(): Promise<void> {
+    this.desk.close();
+    await this.server?.close();
+    this.server = undefined;
+  }
+
+  private steer(worker: WorkerId, text: string): void {
+    this.handles.get(worker)?.steer(text);
+  }
+
+  private onEvent(event: DeskEvent): void {
+    if (event.type === "queue") {
+      this.steer(event.to, queueMessage(event.path, event.queue));
+      return;
+    }
+    if (event.type === "queued") {
+      this.handles.get(event.worker)?.annotate({ note: `queued for ${basename(event.path)} behind ${label(event.holder)}`, noteKind: "info" });
+      return;
+    }
+    this.steer(event.to, grantMessage(event));
+    this.handles.get(event.to)?.annotate({ note: `got ${basename(event.path)} from ${label(event.from)}`, noteKind: "info", waitingFor: undefined });
+  }
+
+  private async handle(request: DeskRequest): Promise<Omit<DeskResponse, "id">> {
+    const worker = request.worker;
+    switch (request.op) {
+      case "hello":
+        this.greeted.add(worker);
+        return { ok: true, text: "desk connected" };
+      case "check":
+        return this.check(worker, request.path ?? "");
+      case "claim":
+        return this.claim(worker, request.path ?? "", request.intent ?? "");
+      case "handover":
+        return this.handover(worker, request.path ?? "", request.note ?? "");
+      case "mine":
+        return { ok: true, text: this.mine(worker) };
+      case "wait":
+        return this.wait(worker, Math.min(MAX_WAIT_MS, Math.max(1000, request.timeoutMs ?? MAX_WAIT_MS)));
+      default:
+        return { ok: false, text: `unknown desk operation ${String(request.op)}` };
+    }
+  }
+
+  private check(worker: WorkerId, path: string): Omit<DeskResponse, "id"> {
+    if (this.desk.holds(worker, path)) return { ok: true, allowed: true, text: "" };
+    const key = this.desk.normalize(path);
+    const holder = this.desk.holderOf(path);
+    if (!holder) {
+      return { ok: true, allowed: false, text: `Claim \`${key}\` first: call claim_file with its path and a one-line intent (what you will change), then retry this edit.` };
+    }
+    return {
+      ok: true,
+      allowed: false,
+      text: `\`${key}\` is checked out by ${label(holder.worker)} (${holder.intent}). Call claim_file to join its queue, keep working on your other files, and edit it once it is handed to you.`,
+    };
+  }
+
+  private claim(worker: WorkerId, path: string, intent: string): Omit<DeskResponse, "id"> {
+    if (!path.trim()) return { ok: false, text: "claim_file needs a path" };
+    const result = this.desk.claim(worker, path, intent);
+    if (result.status === "queued") {
+      return {
+        ok: true,
+        text: `\`${result.path}\` is with ${label(result.holder.worker)} (${result.holder.intent}); you are #${result.position} in line. Keep working on your other files — you will be told when it is handed to you, with their notes.`,
+      };
+    }
+    const behind = result.queue.length > 0 ? ` Waiting behind you: ${queueLines(result.queue)}.` : "";
+    return { ok: true, text: `\`${result.path}\` is yours. Edit it, then call handover_file with a note as soon as you are done with it.${behind}` };
+  }
+
+  private handover(worker: WorkerId, path: string, note: string): Omit<DeskResponse, "id"> {
+    const result = this.desk.handover(worker, path, note);
+    if (!result.ok) return { ok: false, text: result.error };
+    const handover = this.desk.handovers().at(-1);
+    if (result.to && handover) this.options.onHandover?.(handover);
+    if (!result.to) return { ok: true, text: `\`${result.path}\` released; nobody was waiting for it.` };
+    return { ok: true, text: `\`${result.path}\` handed to ${label(result.to.worker)} with your note.` };
+  }
+
+  private mine(worker: WorkerId): string {
+    const waiting = this.desk.waitingFor(worker).map((entry) => `You are #${entry.position} for \`${entry.path}\` (held by ${label(entry.holder.worker)}: ${entry.holder.intent}).`);
+    return [describeHeld(this.desk.heldBy(worker)), ...waiting].join("\n");
+  }
+
+  private async wait(worker: WorkerId, timeoutMs: number): Promise<Omit<DeskResponse, "id">> {
+    const queuedFor = this.desk.waitingFor(worker);
+    if (queuedFor.length > 0) this.handles.get(worker)?.annotate({ waitingFor: basename(queuedFor[0]!.path) });
+    const result = await this.desk.wait(worker, timeoutMs);
+    this.handles.get(worker)?.annotate({ waitingFor: undefined });
+    if (result.refused) {
+      return { ok: false, text: `Hand these over first — others are waiting for them:\n${describeHeld(result.refused)}` };
+    }
+    const grants = result.grants.filter((event): event is Extract<DeskEvent, { type: "granted" }> => event.type === "granted");
+    if (grants.length > 0) return { ok: true, text: grants.map(grantMessage).join("\n") };
+    if (queuedFor.length === 0) return { ok: true, text: "You are not waiting for any file." };
+    return { ok: true, text: `Still waiting:\n${this.mine(worker)}\nIf nothing else is left, finish your report and list the dependency under Notes; files are handed over automatically when their holder finishes.` };
+  }
+}
+
+/** A handover note for `next`, written from a finished worker's report. */
+export function autoNote(from: WorkerId, path: string, next: Claim, changes: ReadonlyArray<{ path: string; change: string }>, completed: string): string {
+  const match = changes.find((change) => change.path.replace(/\\/g, "/").endsWith(path) || path.endsWith(change.path.replace(/\\/g, "/")));
+  const what = match ? `changed it: ${match.change}` : completed ? `finished; its report says: ${completed.replace(/\s+/g, " ").slice(0, 300)}` : "finished without describing its change";
+  return `${label(from)} ${what} (auto-handover on finish; you asked for: ${next.intent})`;
+}

package/src/execution/agent-runner.ts

@@ -2,7 +2,9 @@ import type { Domain, Role } from "../schemas/agent.ts";
 import type { AgentRun } from "../schemas/findings.ts";
 import { roleSpec } from "../roles/registry.ts";
 import { compilePrompt } from "../prompts/compiler.ts";
-import { runPiAgent, spawnPiProcess, type ProcessRunner } from "./pi-runner.ts";
+import { activityDetail, activityWord } from "../pi/activity.ts";
+import { shortDuration, truncate } from "../text.ts";
+import { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner } from "./pi-runner.ts";
 
 export interface AgentContext {
   task: string;
@@ -14,6 +16,16 @@ export interface AgentContext {
   workflowContext?: string;
 }
 
+/** Live fields a caller (the file desk) may set on a running agent. */
+export type LivePatch = Pick<AgentRun, "note" | "noteKind" | "waitingFor">;
+
+/** Control over one running attempt, handed to `onStart`. */
+export interface AgentHandle {
+  runId: string;
+  steer(text: string): void;
+  annotate(patch: LivePatch): void;
+}
+
 export interface AgentRequest {
   taskId: string;
   domain: Domain;
@@ -28,15 +40,50 @@ export interface AgentRequest {
   cwd: string;
   signal?: AbortSignal;
   onUpdate?: (run: AgentRun) => void;
-  /** Bounded retries for transient failures (crash/timeout). */
+  /** Bounded retries for transient failures (crash/stall). */
   retries?: number;
+  /** Kill after this long without output; 0 or absent disables. */
+  stallTimeoutMs?: number;
+  /** Silence allowed while one tool call runs. */
+  toolStallTimeoutMs?: number;
+  /** Fraction of `timeoutMs` at which the agent is asked to wrap up; 0 disables. */
+  wrapUpAt?: number;
+  /** Extra tools on top of the role allowlist (the file desk's tools). */
+  extraTools?: readonly string[];
+  env?: Record<string, string>;
+  /** Called once per attempt when the process is running. */
+  onStart?: (handle: AgentHandle) => void;
+  /** Called once per attempt after it ends, before any retry. */
+  onAttemptEnd?: (run: AgentRun) => void;
+}
+
+/** The watchdog fields of an AgentRequest, taken from the workflow config. */
+export function watchdogOptions(workflow: {
+  maxAgentRetries: number;
+  stallTimeoutMs: number;
+  toolStallTimeoutMs: number;
+  wrapUpAt: number;
+}): Pick<AgentRequest, "retries" | "stallTimeoutMs" | "toolStallTimeoutMs" | "wrapUpAt"> {
+  return {
+    retries: workflow.maxAgentRetries,
+    stallTimeoutMs: workflow.stallTimeoutMs,
+    toolStallTimeoutMs: workflow.toolStallTimeoutMs,
+    wrapUpAt: workflow.wrapUpAt,
+  };
 }
 
 const activeControllers = new Set<AbortController>();
 
+/** A stall or crash is worth one more try; a spent deadline or a cancel is not. */
+function retryable(run: AgentRun): boolean {
+  if (run.status === "failed") return true;
+  return run.status === "timeout" && run.stalled === true;
+}
+
 /**
  * Run one domain/role agent, retrying transient failures a bounded number of
- * times. Cancellation never retries, so Esc/quit stays responsive.
+ * times. Cancellation and a spent deadline never retry, so Esc stays responsive
+ * and a slow agent cannot double its time budget.
  */
 export async function runAgent(request: AgentRequest, run: ProcessRunner = spawnPiProcess): Promise<AgentRun> {
   const startedAt = new Date().toISOString();
@@ -44,7 +91,8 @@ export async function runAgent(request: AgentRequest, run: ProcessRunner = spawn
   let last: AgentRun | undefined;
   for (let attempt = 1; attempt <= attempts; attempt++) {
     last = await runAgentOnce(request, run, attempt, startedAt);
-    if (last.status === "success" || last.status === "cancelled") break;
+    request.onAttemptEnd?.(last);
+    if (!retryable(last)) break;
   }
   return last!;
 }
@@ -66,9 +114,16 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
     output: "",
     attempts,
     startedAt,
+    ...(attempts > 1 ? { note: `retry ${attempts - 1} of ${(request.retries ?? 0)}`, noteKind: "warning" as const } : {}),
   };
 }
 
+function toolsFor(request: AgentRequest): readonly string[] | undefined {
+  const tools = roleSpec(request.role).tools;
+  if (!request.extraTools?.length) return tools;
+  return [...(tools ?? []), ...request.extraTools];
+}
+
 /**
  * Run one domain/role agent in an isolated pi process. The role's tool
  * allowlist comes from its spec, so read-only roles cannot modify anything.
@@ -76,24 +131,46 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
 async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt: number, startedAt: string): Promise<AgentRun> {
   const base = baseRun(request, `${request.taskId}:${request.domain}:${request.role}:${Date.now().toString(36)}`, startedAt, attempt);
   request.onUpdate?.(base);
+  const live = createLiveRun(base, request);
 
   const controller = new AbortController();
   activeControllers.add(controller);
   const signal = request.signal ? AbortSignal.any([request.signal, controller.signal]) : controller.signal;
   try {
     const systemPrompt = compilePrompt({ domain: request.domain, role: request.role, ...request.context });
+    const wrapUp = request.wrapUpAt && request.wrapUpAt > 0 && request.wrapUpAt < 1 ? Math.floor(request.timeoutMs * request.wrapUpAt) : 0;
     const result = await runPiAgent({
       cwd: request.cwd,
       task: request.instruction,
       systemPrompt,
-      tools: roleSpec(request.role).tools,
+      tools: toolsFor(request),
       model: request.model,
       thinking: request.thinking,
       timeoutMs: request.timeoutMs,
       signal,
-      onActivity: activityReporter(base, request),
+      env: request.env,
+      stallTimeoutMs: request.stallTimeoutMs,
+      toolStallTimeoutMs: request.toolStallTimeoutMs,
+      wrapUpAtMs: wrapUp,
+      onEvent: live.onEvent,
+      onStart: (handle) => request.onStart?.({ runId: base.runId, steer: handle.steer, annotate: live.annotate }),
     }, run);
-    const final: AgentRun = { ...base, status: result.status, output: result.output, error: result.error, usage: result.usage, finishedAt: new Date().toISOString() };
+    const current = live.current();
+    const final: AgentRun = {
+      ...base,
+      status: result.status,
+      output: result.output,
+      error: result.error ? describeError(result.error, current, result.stalled === true) : undefined,
+      usage: result.usage,
+      finishedAt: new Date().toISOString(),
+      turns: current.turns ?? (result.usage.turns || undefined),
+      tools: current.tools,
+      model: result.model ?? current.model,
+      ...(result.stalled ? { stalled: true } : {}),
+      ...(result.wrappedUp ? { wrappedUp: true } : {}),
+      note: undefined,
+      noteKind: undefined,
+    };
     request.onUpdate?.(final);
     return final;
   } finally {
@@ -101,14 +178,78 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
   }
 }
 
-/** Streams activity-word changes for one run, deduping consecutive repeats. */
-function activityReporter(base: AgentRun, request: AgentRequest): (activity: string) => void {
-  let last: string | undefined;
-  return (activity) => {
-    if (activity === last) return;
-    last = activity;
-    request.onUpdate?.({ ...base, activity });
+/** Name what the agent was doing when a stall or deadline hit. */
+function describeError(error: string, current: AgentRun, stalled: boolean): string {
+  if (!stalled && !/time limit/.test(error)) return error;
+  const doing = current.activity ? ` while ${current.activity}${current.detail ? ` ${current.detail}` : ""}` : "";
+  return `${error}${doing}`;
+}
+
+const THROTTLE_MS = 2000;
+
+/**
+ * Tracks one attempt's live state from its stream and reports it through
+ * `onUpdate`: activity changes, retries and notes immediately, counters and
+ * heartbeats at most every couple of seconds.
+ */
+function createLiveRun(base: AgentRun, request: AgentRequest) {
+  let state: AgentRun = base;
+  let lastEmit = 0;
+  const emit = (patch: Partial<AgentRun>, force: boolean) => {
+    state = { ...state, ...patch, lastEventAt: Date.now() };
+    const now = Date.now();
+    if (!force && now - lastEmit < THROTTLE_MS) return;
+    lastEmit = now;
+    request.onUpdate?.(state);
+  };
+  const changed = (activity: string, detail: string | undefined) => activity !== state.activity || detail !== state.detail;
+  const onEvent = (event: PiStreamEvent) => {
+    switch (event.type) {
+      case "tool_execution_start": {
+        const activity = activityWord(event.toolName);
+        const detail = activityDetail(event.toolName, event.args);
+        emit({ activity, detail, tools: (state.tools ?? 0) + 1 }, changed(activity, detail));
+        return;
+      }
+      case "thinking":
+      case "writing":
+        emit({ activity: event.type, detail: undefined }, changed(event.type, undefined));
+        return;
+      case "turn_start":
+        emit({ turns: (state.turns ?? 0) + 1 }, false);
+        return;
+      case "retry":
+        emit({ note: `provider retry ${event.attempt}/${event.maxAttempts}: ${truncateLine(event.error)}`, noteKind: "warning" }, true);
+        return;
+      case "retry_end":
+        emit({ note: undefined, noteKind: undefined }, true);
+        return;
+      case "compaction":
+        emit({ note: "compacting context", noteKind: "info" }, true);
+        return;
+      case "wrap_up":
+        emit({ note: `asked to wrap up (${shortDuration(request.timeoutMs)} limit)`, noteKind: "warning", wrappedUp: true }, true);
+        return;
+      case "usage": {
+        const usage = state.usage ?? { input: 0, output: 0, cost: 0, turns: 0 };
+        const next = { input: usage.input + event.input, output: usage.output + event.output, cost: usage.cost + event.cost, turns: usage.turns + 1 };
+        emit({ usage: next, model: event.model ?? state.model }, false);
+        return;
+      }
+      default:
+        emit({}, false);
+    }
   };
+  return {
+    onEvent,
+    annotate: (patch: LivePatch) => emit(patch, true),
+    current: () => state,
+  };
+}
+
+function truncateLine(text: string): string {
+  const first = text.split("\n")[0] ?? "";
+  return truncate(first, 48).split("\n")[0]!;
 }
 
 async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: number, fn: (item: TIn) => Promise<TOut>): Promise<TOut[]> {
@@ -126,6 +267,11 @@ async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: num
   return results;
 }
 
+/** Run independent tasks concurrently, bounded by `limit`. */
+export async function mapConcurrent<TIn, TOut>(items: TIn[], limit: number, fn: (item: TIn) => Promise<TOut>): Promise<TOut[]> {
+  return mapWithConcurrencyLimit(items, limit, fn);
+}
+
 /** Run independent agents concurrently, bounded by `limit`. */
 export async function runParallel(requests: AgentRequest[], limit: number, run: ProcessRunner = spawnPiProcess): Promise<AgentRun[]> {
   return mapWithConcurrencyLimit(requests, limit, (request) => runAgent(request, run));