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

package/src/desk/session.ts

@@ -8,10 +8,20 @@ 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";
+import { appendPost, formatPost, isPostKind, PUSHED_KINDS, SUBSCRIPTIONS, subscriptionFor, type BoardPost } from "./board.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"];
 
+/** The desk tools of a worker with a checkout of its own: questions only, no claims. */
+export const PEER_TOOLS: readonly string[] = ["ask_peer", "answer_peer"];
+
+/** How long `ask_peer` waits for an answer by default, and at most. */
+export const ASK_WAIT_MS = 90_000;
+export const MAX_ASK_WAIT_MS = 180_000;
+const MAX_QUESTION = 800;
+const MAX_ANSWER = 1500;
+
 /** 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;
 
@@ -29,6 +39,27 @@ function label(worker: WorkerId): string {
   return names[worker] ?? worker.toUpperCase();
 }
 
+/** A peer named the way workers know each other (DEV, DESIGN, QA) or by domain. */
+export function peerId(name: string): WorkerId {
+  const key = name.trim().toLowerCase();
+  const ids: Record<string, string> = { dev: "backend", backend: "backend", design: "designer", designer: "designer", qa: "qa" };
+  return ids[key] ?? name.trim();
+}
+
+function flat(text: string, max: number): string {
+  const value = text.replace(/\s+/g, " ").trim();
+  return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+interface PeerQuestion {
+  id: number;
+  from: WorkerId;
+  to: WorkerId;
+  question: string;
+  resolve: (answer: string | undefined) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
 function queueLines(queue: readonly Claim[]): string {
   return queue.map((claim, index) => `${index + 1}) ${label(claim.worker)} — ${claim.intent}`).join("; ");
 }
@@ -58,6 +89,12 @@ function describeHeld(files: readonly FileView[]): string {
 
 export interface DeskSessionOptions {
   cwd: string;
+  /** The task board's file: workers post to it through the desk, and contracts and blockers reach the other workers at once. */
+  boardPath?: string;
+  /** False when every worker has a checkout of its own: edits need no claim, and the desk only carries questions and the board. */
+  claims?: boolean;
+  /** Workers of one parallel batch may ask each other questions (`ask_peer`). */
+  peers?: boolean;
   /** A worker that finished without handing a file over leaves this note for the next worker. */
   onHandover?: (handover: Handover) => void;
 }
@@ -75,6 +112,8 @@ export class DeskSession {
   private readonly handles = new Map<WorkerId, AgentHandle>();
   private readonly greeted = new Set<WorkerId>();
   private readonly options: DeskSessionOptions;
+  private readonly questions = new Map<number, PeerQuestion>();
+  private nextQuestion = 1;
 
   constructor(options: DeskSessionOptions) {
     this.options = options;
@@ -97,6 +136,16 @@ export class DeskSession {
     this.handles.set(worker, handle);
   }
 
+  /** False when every worker has a checkout of its own and edits need no claim. */
+  get usesClaims(): boolean {
+    return this.options.claims !== false;
+  }
+
+  /** The desk tools its workers get: claims, questions, or both. */
+  tools(): readonly string[] {
+    return [...(this.usesClaims ? DESK_TOOLS : []), ...(this.options.peers ? PEER_TOOLS : [])];
+  }
+
   /** True once the worker's desk extension has checked in. */
   greetedBy(worker: WorkerId): boolean {
     return this.greeted.has(worker);
@@ -106,8 +155,13 @@ export class DeskSession {
   release(worker: WorkerId, note: (path: string, next: Claim) => string): void {
     this.releaseFiles(worker, note);
     this.handles.delete(worker);
+    // A finished worker can no longer answer, and its own questions need no answer.
+    for (const question of [...this.questions.values()]) {
+      if (question.to === worker || question.from === worker) this.settle(question, undefined);
+    }
   }
 
+
   /** A coordinating worker releases claims but still receives steering messages. */
   releaseFiles(worker: WorkerId, note: (path: string, next: Claim) => string): void {
     this.handles.get(worker)?.annotate({ waitingFor: undefined });
@@ -119,6 +173,7 @@ export class DeskSession {
   }
 
   async close(): Promise<void> {
+    for (const question of [...this.questions.values()]) this.settle(question, undefined);
     if (this.server) sessions.delete(this.server.address);
     this.desk.close();
     await this.server?.close();
@@ -158,13 +213,19 @@ export class DeskSession {
         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)));
+      case "post":
+        return this.post(request.from?.trim() || worker, worker, request.kind ?? "", request.text ?? "", request.files ?? []);
+      case "ask":
+        return this.ask(worker, request.to ?? "", request.path ?? "", request.text ?? "", Math.min(MAX_ASK_WAIT_MS, Math.max(5000, request.timeoutMs ?? ASK_WAIT_MS)));
+      case "answer":
+        return this.answer(worker, request.questionId ?? 0, request.text ?? "");
       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: "" };
+    if (this.options.claims === false || 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) {
@@ -217,6 +278,73 @@ export class DeskSession {
     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.` };
   }
+
+  private post(from: string, worker: WorkerId, kind: string, text: string, files: readonly string[]): Omit<DeskResponse, "id"> {
+    if (!this.options.boardPath) return { ok: false, text: "This task has no board." };
+    if (!isPostKind(kind)) return { ok: false, text: `Unknown post kind "${kind}".` };
+    let post: BoardPost;
+    try {
+      post = appendPost(this.options.boardPath, { from, kind, text, files: files.map((file) => this.desk.normalize(file)) });
+    } catch (error) {
+      return { ok: false, text: (error as Error).message };
+    }
+    let told: string[] = [];
+    if (PUSHED_KINDS.has(post.kind)) {
+      // Only the batch's named workers hear posts as they land; children read the board when they need it.
+      told = [...this.handles.keys()].filter((peer) => peer !== worker && peer in SUBSCRIPTIONS && subscriptionFor(peer).includes(post.kind));
+      for (const peer of told) this.steer(peer, `bot-lobby board: ${formatPost(post)}`);
+    }
+    return { ok: true, text: `Posted #${post.seq}.${told.length > 0 ? ` ${told.map(label).join(", ")} ${told.length === 1 ? "was" : "were"} told now.` : ""}` };
+  }
+
+  private async ask(worker: WorkerId, to: string, path: string, question: string, timeoutMs: number): Promise<Omit<DeskResponse, "id">> {
+    if (!this.options.peers) return { ok: false, text: "No peers work alongside you here." };
+    const text = flat(question, MAX_QUESTION);
+    if (!text) return { ok: false, text: "ask_peer needs a question." };
+    if (path.trim() && !this.usesClaims) return { ok: false, text: "Every worker in this batch has a checkout of its own, so nobody holds files: name the peer (DEV, DESIGN or QA) instead." };
+    const target = path.trim() ? this.desk.holderOf(path)?.worker : to.trim() ? peerId(to) : undefined;
+    if (!target) return { ok: false, text: path.trim() ? `Nobody holds \`${this.desk.normalize(path)}\`; read it yourself.` : "Name the peer (DEV, DESIGN or QA) or a file its holder should answer about." };
+    if (target === worker) return { ok: false, text: "That is you." };
+    if (!this.handles.has(target)) return { ok: false, text: `${label(target)} is not working right now. Post a \`question\` on the board instead; the oracle sees it.` };
+    // A worker waiting on its own question cannot answer until that returns: asking it would chain the waits (or close a cycle).
+    const theirs = [...this.questions.values()].find((entry) => entry.from === target);
+    if (theirs?.to === worker) return { ok: false, text: `${label(target)} is waiting on your answer to its question #${theirs.id} ("${theirs.question}"). Answer it with answer_peer first.` };
+    if (theirs) return { ok: false, text: `${label(target)} is waiting on an answer from ${label(theirs.to)} and cannot answer yet. Carry on with your other work and ask again shortly, or post a \`question\` on the board.` };
+    const id = this.nextQuestion++;
+    const answer = await new Promise<string | undefined>((resolve) => {
+      const timer = setTimeout(() => this.settle(this.questions.get(id), undefined), timeoutMs);
+      this.questions.set(id, { id, from: worker, to: target, question: text, resolve, timer });
+      this.steer(target, `bot-lobby desk: question #${id} from ${label(worker)}: ${text} Answer it now with answer_peer (id ${id}) in a line or two, from what you know or have built, then carry on with your own work. It is a question, not a task: you take work only from your brief.`);
+      this.handles.get(worker)?.annotate({ note: `asked ${label(target)}`, noteKind: "info" });
+    });
+    if (answer === undefined) {
+      return { ok: true, text: `${label(target)} did not answer within ${Math.round(timeoutMs / 1000)} seconds (it may be in a long command, or it finished). Carry on with your best reading of the brief and the board, and list the open question under Notes.` };
+    }
+    if (this.options.boardPath) {
+      try {
+        appendPost(this.options.boardPath, { from: worker, kind: "note", text: `Asked ${label(target)}: ${text} Answer: ${answer}` });
+      } catch {
+        // The answer still reaches the asker.
+      }
+    }
+    return { ok: true, text: `${label(target)} answers: ${answer}` };
+  }
+
+  private answer(worker: WorkerId, id: number, text: string): Omit<DeskResponse, "id"> {
+    const question = this.questions.get(id);
+    if (!question || question.to !== worker) return { ok: false, text: `There is no open question #${id} for you (it may have timed out).` };
+    const answer = flat(text, MAX_ANSWER);
+    if (!answer) return { ok: false, text: "answer_peer needs an answer." };
+    this.settle(question, answer);
+    return { ok: true, text: `Answer sent to ${label(question.from)}.` };
+  }
+
+  private settle(question: PeerQuestion | undefined, answer: string | undefined): void {
+    if (!question || !this.questions.has(question.id)) return;
+    clearTimeout(question.timer);
+    this.questions.delete(question.id);
+    question.resolve(answer);
+  }
 }
 
 /** A handover note for `next`, written from a finished worker's report. */

package/src/execution/agent-runner.ts

@@ -44,11 +44,15 @@ export interface AgentRequest {
   instruction: string;
   /** Prompt layers selected for this run. */
   context: AgentContext;
+  /** A whole system prompt of its own instead of the compiled role layers (the goal check). */
+  systemPrompt?: string;
   model?: string;
   mcpTools?: string[];
   /** False when the agent's settings turn its auto-compaction off. */
   autoCompact?: boolean;
-  delegationQuota?: { used: number };
+  delegationQuota?: { used: number; consults?: number };
+  /** See PiRunOptions.expert. */
+  expert?: { model?: string; thinking: string };
   thinking?: string;
   timeoutMs: number;
   cwd: string;
@@ -240,7 +244,7 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
   };
   arm();
   try {
-    const systemPrompt = compilePrompt({ domain: request.domain, role: request.role, ...request.context });
+    const systemPrompt = request.systemPrompt ?? compilePrompt({ domain: request.domain, role: request.role, ...request.context });
     const left = Math.max(1, time.endsAt - Date.now());
     const reportMs = Math.min(REPORT_GRACE_MS, Math.floor(left / 4));
     const wrapUp = Math.floor(left * (request.wrapUpAt || 0.75));
@@ -249,6 +253,7 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
       cwd: request.cwd,
       agent: { runId: base.runId, taskId: request.taskId, domain: request.domain, role: request.role },
       delegationQuota: quota,
+      ...(request.expert ? { expert: request.expert } : {}),
       effort: request.effort,
       effortProfile: request.effortProfile,
       onChildRun: (child) => {
@@ -353,7 +358,10 @@ async function mapWithConcurrencyLimit<TIn, TOut>(items: TIn[], concurrency: num
       results[index] = await fn(items[index]!);
     }
   });
-  await Promise.all(workers);
+  // Every worker settles before a failure is raised, so no caller cleans up under a sibling still running.
+  const settled = await Promise.allSettled(workers);
+  const failed = settled.find((entry): entry is PromiseRejectedResult => entry.status === "rejected");
+  if (failed) throw failed.reason;
   return results;
 }
 

package/src/execution/delegation.ts

@@ -7,16 +7,32 @@ import type { AgentRun } from "../schemas/findings.ts";
 import type { Domain, Role } from "../schemas/agent.ts";
 import { effortFor } from "../classifier/instance.ts";
 import { fellShort, profileLabel, routeLabel } from "../classifier/effort.ts";
-import { agentProfile } from "../schemas/configuration.ts";
+import { agentProfile, expertProfile } from "../schemas/configuration.ts";
+import { loadPrompt } from "../prompts/loader.ts";
 import { dataRoot, detectProjectRoot, loadConfig } from "../state/project.ts";
 import { EditLog } from "../state/changes.ts";
 import { createLiveRun } from "./live-run.ts";
 import { runPiAgent, type PiRunOptions, type ProcessRunner } from "./pi-runner.ts";
 import { startDeskServer } from "../desk/ipc.ts";
-import { DESK_ENV, DESK_TOOLS, DeskSession, deskSessionAt } from "../desk/session.ts";
+import { DESK_ENV, DeskSession, deskSessionAt, PEER_TOOLS } from "../desk/session.ts";
+import { BOARD_ENV } from "../desk/board.ts";
 
 export const MAX_CHILDREN = 5;
 export const DELEGATE_TOOL = "delegate_subtasks";
+export const EXPERT_TOOL = "ask_expert";
+/** Consults one step may make: advice on the hard part, not a second worker. */
+export const MAX_CONSULTS = 2;
+/** Longest an expert may take to answer. */
+export const EXPERT_TIMEOUT_MS = 5 * 60 * 1000;
+/** Marks an expert's run, so its host gives it an adviser's note rather than a child's. */
+export const EXPERT_ENV = "BOT_LOBBY_EXPERT";
+
+/** The worker's env without its desk and board: an expert only reads and answers. */
+function withoutTeamEnv(env: Record<string, string> | undefined): Record<string, string> {
+  const { [DESK_ENV.address]: _address, [DESK_ENV.worker]: _worker, [BOARD_ENV]: _board, BOT_LOBBY_BOARD_FROM: _from, ...rest } = env ?? {};
+  return rest;
+}
+const EXPERT_TOOLS = ["read", "grep", "find", "ls"];
 export const AGENT_ENV = "BOT_LOBBY_AGENT_POLICY";
 export const DELEGATION_ENV = "BOT_LOBBY_DELEGATION";
 
@@ -27,6 +43,12 @@ export function canDelegate(agent: { role: Role; domain: Domain; depth?: number
   return agent.role === "reviewer" && agent.domain === "qa";
 }
 
+/** A task's DESIGN/DEV workers (not their children, nor quick fixes) may consult a stronger model, when the setting is on. */
+export function canConsult(agent: { runId: string; taskId: string; role: Role; domain: Domain; depth?: number }, enabled: boolean): boolean {
+  // A lobby job (a quick fix) runs as its own task: it is one agent on a small change, not a task's worker.
+  return enabled && agent.taskId !== agent.runId && (agent.depth ?? 1) === 1 && agent.role === "worker" && (agent.domain === "designer" || agent.domain === "backend");
+}
+
 /** One shared child pool per task; parents waiting on children never hold its slots. */
 const pools = new Map<string, { active: number; users: number; waiters: Array<() => void> }>();
 
@@ -72,16 +94,22 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
   const agent = options.agent ?? { runId: id, taskId: id, domain: "backend" as const, role: editable ? "worker" as const : "reviewer" as const };
   const depth = agent.depth ?? 1;
   const quota = options.delegationQuota ?? { used: 0 };
-  const tools = [...new Set([...baseTools, "codemode", "tool_search", ...(canDelegate(agent, quota.used) ? [DELEGATE_TOOL] : [])])];
+  const consults = canConsult(agent, config.workflow.consultExpert);
+  const tools = [...new Set([...baseTools, "codemode", "tool_search", ...(canDelegate(agent, quota.used) ? [DELEGATE_TOOL] : []), ...(consults ? [EXPERT_TOOL] : [])])];
   const mcpTools = options.mcpTools ?? agentProfile(config, agent.domain, agent.role).mcpTools ?? [];
   const policy: AgentPolicy = { tools, mcpTools, readOnly: !editable, depth };
-  if (depth > 1) return { tools, mcpTools, env: { ...options.env, [AGENT_ENV]: JSON.stringify(policy), [DELEGATION_ENV]: "" }, note: "You are a child agent. Finish only your assigned brief and report evidence to your parent; you cannot delegate further.", close: async () => {}, onStart: options.onStart, children: [] as AgentRun[] };
+  if (depth > 1) return { tools, mcpTools, env: { ...options.env, [AGENT_ENV]: JSON.stringify(policy), [DELEGATION_ENV]: "" }, note: options.env?.[EXPERT_ENV] ? "You are advising a worker: read what you need, answer its question, and change nothing." : "You are a child agent. Finish only your assigned brief and report evidence to your parent; you cannot delegate further.", close: async () => {}, onStart: options.onStart, children: [] as AgentRun[] };
 
   const address = options.env?.[DESK_ENV.address];
   let desk = address ? deskSessionAt(address) : undefined;
   if (address && !desk) throw new Error("The inherited file desk is unavailable.");
-  const ownedDesk = editable && !desk ? new DeskSession({ cwd: options.cwd }) : undefined;
-  if (ownedDesk) { await ownedDesk.open(); desk = ownedDesk; }
+  const board = options.env?.[BOARD_ENV];
+  // A worker with a checkout of its own (no claims on the batch desk) still needs claims among its children.
+  const ownedDesk = editable && (!desk || !desk.usesClaims) ? new DeskSession({ cwd: options.cwd, ...(board ? { boardPath: board } : {}) }) : undefined;
+  if (ownedDesk) await ownedDesk.open();
+  // Children claim files among themselves; the parent keeps the batch desk (and its peers) when it has one.
+  const childDesk = ownedDesk ?? desk;
+  desk ??= ownedDesk;
   const controller = new AbortController();
   const lifetime = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
   let timeController = new AbortController();
@@ -129,7 +157,7 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
         task: brief,
         model,
         thinking,
-        tools: [...new Set([...tools.filter((tool) => tool !== DELEGATE_TOOL), ...(desk ? DESK_TOOLS : [])])],
+        tools: [...new Set([...tools.filter((tool) => tool !== DELEGATE_TOOL && tool !== EXPERT_TOOL), ...(childDesk ? childDesk.tools().filter((tool) => !PEER_TOOLS.includes(tool)) : [])])],
         mcpTools,
         timeoutMs: left,
         signal,
@@ -138,8 +166,8 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
         delegationQuota: undefined,
         onChildRun: undefined,
         onEvent: live.onEvent,
-        env: { ...options.env, ...(desk ? desk.env(childId) : {}) },
-        onStart: (handle) => desk?.attach(childId, { runId: childId, steer: handle.steer, annotate: live.annotate }),
+        env: { ...options.env, ...(childDesk ? childDesk.env(childId) : {}) },
+        onStart: (handle) => childDesk?.attach(childId, { runId: childId, steer: handle.steer, annotate: live.annotate }),
       }, run);
       };
       let result = await attempt(route?.model ?? configured.model, route?.thinking ?? configured.thinking);
@@ -156,20 +184,88 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
       update(final);
       return final;
     } finally {
-      desk?.release(childId, () => "Child finished; re-read the file and check its report before continuing.");
+      childDesk?.release(childId, () => "Child finished; re-read the file and check its report before continuing.");
     }
   };
 
+  // Kept on the quota, which a step's retries share, so a retry does not grant fresh consults.
+  quota.consults ??= 0;
+  const consultations = new Map<string, AbortController>();
+  const consult = async (question: string, signal: AbortSignal): Promise<{ ok: boolean; text: string }> => {
+    const left = Math.min(EXPERT_TIMEOUT_MS, deadlineAt - Date.now());
+    if (left < 30_000) return { ok: false, text: "Too little of your time is left to consult; carry on with your best reading." };
+    // The oracle resolves the expert (its session model when settings name none); settings alone, then the worker's own, without it.
+    const settled = options.expert ?? expertProfile(config);
+    const expert = { model: settled.model ?? options.model, thinking: settled.thinking };
+    const expertId = randomUUID();
+    const base: AgentRun = { runId: expertId, parentRunId: id, depth: 2, taskId: agent.taskId, domain: agent.domain, role: "reviewer", instruction: question, stepInstruction: options.task, status: "running", endsAt: Date.now() + left, output: "", attempts: 1, startedAt: new Date().toISOString(), thinking: expert.thinking, ...(expert.model ? { model: expert.model } : {}), note: "expert consult", noteKind: "info" };
+    const live = createLiveRun(base, { onUpdate: update, timeoutMs: left }, new EditLog(options.cwd));
+    update(base);
+    let final: AgentRun;
+    try {
+      const result = await runPiAgent({
+        cwd: options.cwd,
+        agent: { ...agent, runId: expertId, role: "reviewer", depth: 2 },
+        task: [`A worker asks: ${question}`, `The worker's brief, for context:\n${options.task.slice(0, 8000)}`].join("\n\n"),
+        systemPrompt: loadPrompt("expert.md"),
+        tools: EXPERT_TOOLS,
+        mcpTools: [],
+        ...(expert.model ? { model: expert.model } : {}),
+        thinking: expert.thinking,
+        timeoutMs: left,
+        wrapUpAtMs: Math.floor(left * 0.8),
+        ...(options.stallTimeoutMs !== undefined ? { stallTimeoutMs: options.stallTimeoutMs } : {}),
+        ...(options.toolStallTimeoutMs !== undefined ? { toolStallTimeoutMs: options.toolStallTimeoutMs } : {}),
+        signal,
+        onEvent: live.onEvent,
+        // Its own env: the expert is not one of the worker's children, nor on its desk or board.
+        env: { ...withoutTeamEnv(options.env), [EXPERT_ENV]: "1" },
+      }, run);
+      final = { ...live.current(), ...result, finishedAt: new Date().toISOString(), note: undefined, noteKind: undefined };
+    } catch (error) {
+      final = { ...live.current(), status: signal.aborted ? "cancelled" : "failed", error: (error as Error).message, finishedAt: new Date().toISOString(), note: undefined, noteKind: undefined };
+    }
+    update(final);
+    if (final.status === "success" && final.output.trim()) return { ok: true, text: final.output.trim().slice(0, 8000) };
+    // An expert that never answered does not use up a consult.
+    quota.consults = Math.max(0, (quota.consults ?? 1) - 1);
+    return { ok: false, text: `The expert did not answer (${final.status}${final.error ? `: ${final.error}` : ""}); carry on with your best reading.` };
+  };
+
   const token = randomUUID();
   const server = await startDeskServer(async (request) => {
     if (request.worker !== token) return { ok: false, text: "Unknown parent agent." };
     if (request.op === "cancel_delegate") { controller.abort(); return { ok: true, text: "Children cancelled." }; }
+    if (request.op === "cancel_consult") {
+      consultations.get(request.consultId ?? "")?.abort();
+      return { ok: true, text: "Consult cancelled." };
+    }
+    if (request.op === "consult") {
+      if (!consults) return { ok: false, text: "Consulting is off for this agent." };
+      if ((quota.consults ?? 0) >= MAX_CONSULTS) return { ok: false, text: `You have used your ${MAX_CONSULTS} consults for this step; decide with what you have, or report the open question.` };
+      const question = (request.text ?? "").trim();
+      if (!question) return { ok: false, text: "ask_expert needs a question." };
+      quota.consults = (quota.consults ?? 0) + 1;
+      // Its own controller, so the worker abandoning its tool call stops this expert and nothing else.
+      const own = new AbortController();
+      const parent = childSignal();
+      const stop = () => own.abort();
+      parent.addEventListener("abort", stop, { once: true });
+      const consultId = request.consultId ?? randomUUID();
+      consultations.set(consultId, own);
+      try {
+        return await consult(question.slice(0, 6000), own.signal);
+      } finally {
+        consultations.delete(consultId);
+        parent.removeEventListener("abort", stop);
+      }
+    }
     if (request.op !== "delegate") return { ok: false, text: "Unknown delegation operation." };
     const signal = childSignal();
     signal.throwIfAborted();
     const briefs = reserveChildren(quota, request.briefs);
     // A coordinating parent must release claims before waiting for children that may need them.
-    desk?.releaseFiles(parentDeskId, () => "Delegating this work; re-read before editing.");
+    for (const held of new Set([desk, childDesk])) held?.releaseFiles(parentDeskId, () => "Delegating this work; re-read before editing.");
     const runs = briefs.map((brief) => {
       const promise = inPool(key, Math.max(1, config.workflow.maxParallelWorkers), signal, () => childRun(brief, signal));
       pending.add(promise);
@@ -188,10 +284,10 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
 
   let closed = false;
   return {
-    tools: desk ? [...new Set([...tools, ...DESK_TOOLS])] : tools,
+    tools: desk ? [...new Set([...tools, ...desk.tools()])] : tools,
     mcpTools,
-    env: { ...options.env, ...(desk ? desk.env(parentDeskId) : {}), [AGENT_ENV]: JSON.stringify({ ...policy, tools: desk ? [...new Set([...tools, ...DESK_TOOLS])] : tools }), [DELEGATION_ENV]: JSON.stringify({ address: server.address, token, timeoutMs: options.timeoutMs }) },
-    note: `${canDelegate(agent, quota.used) ? `Work directly when you can finish the brief yourself. Use ${DELEGATE_TOOL} only for useful, separable work with disjoint files, at most five children total; children share your remaining time and cannot delegate further. Integrate and verify their work yourself. ` : ""}Use codemode for concise parallel calls, inspect failures, and return only useful evidence.${desk ? " Before edit/write, claim_file; handover_file when finished. Release files before delegating or waiting." : ""}`,
+    env: { ...options.env, ...(desk ? desk.env(parentDeskId) : {}), [AGENT_ENV]: JSON.stringify({ ...policy, tools: desk ? [...new Set([...tools, ...desk.tools()])] : tools }), [DELEGATION_ENV]: JSON.stringify({ address: server.address, token, timeoutMs: options.timeoutMs }) },
+    note: `${consults ? `When you are stuck on a hard step after a real attempt, or about to make a choice you are unsure of (a tricky algorithm, a subtle bug, an unfamiliar API), ${EXPERT_TOOL} asks a stronger model for advice, at most ${MAX_CONSULTS} times; it reads the repository and answers, you still do the work. ` : ""}${canDelegate(agent, quota.used) ? `Work directly when you can finish the brief yourself. Use ${DELEGATE_TOOL} only for useful, separable work with disjoint files, at most five children total; children share your remaining time and cannot delegate further. Integrate and verify their work yourself. ` : ""}Use codemode for concise parallel calls, inspect failures, and return only useful evidence.${desk?.usesClaims ? " Before edit/write, claim_file; handover_file when finished. Release files before delegating or waiting." : ""}`,
     onStart: (handle: Parameters<NonNullable<PiRunOptions["onStart"]>>[0]) => {
       desk?.attach(parentDeskId, { runId: id, steer: handle.steer, annotate: () => {} });
       options.onStart?.(handle);
@@ -211,7 +307,7 @@ export async function delegationHost(options: PiRunOptions, run: ProcessRunner)
       clearTimeout(deadline);
       await Promise.allSettled([...pending]);
       await server.close();
-      if (ownedDesk) { desk?.release(parentDeskId, () => "Parent finished; re-read before editing."); await ownedDesk.close(); }
+      if (ownedDesk) { ownedDesk.release(parentDeskId, () => "Parent finished; re-read before editing."); await ownedDesk.close(); }
       pool.users -= 1;
       if (pool.users === 0) pools.delete(key);
     },

package/src/execution/pi-runner.ts

@@ -29,7 +29,9 @@ export interface PiRunOptions {
   effortProfile?: RunProfileLike;
   agent?: { runId: string; taskId: string; domain: Domain; role: Role; depth?: number };
   mcpTools?: string[];
-  delegationQuota?: { used: number };
+  delegationQuota?: { used: number; consults?: number };
+  /** The model and thinking ask_expert consults on, resolved by the oracle (its session model when settings name none). */
+  expert?: { model?: string; thinking: string };
   onChildRun?: (run: AgentRun) => void;
   cwd: string;
   task: string;