@a-t-h-i/bot-lobby 0.6.33 → 0.6.35

package/README.md

@@ -124,3 +124,33 @@ Settings live in `~/.pi/bot-lobby/config.json` (`BOT_LOBBY_CONFIG_DIR` moves the
 `/bot-lobby config` shows what is in effect. Colour themes you import, under a name you choose,
 are kept in `themes.json` beside it, so every Pi session and project shows them. Tasks and
 project knowledge stay in `.pi/bot-lobby/` inside your project.
+
+
+Requires **Pi 1.0.x** (1.0.1 or later). Every bot-lobby agent can use
+`delegate_subtasks` for substantial, separable work. Each parent gets five child
+slots total, shared across retries; children inherit its model, thinking, role,
+permissions, worktree and remaining time. Children report to their parent, which
+integrates and verifies the result. Children cannot delegate further. Active
+children share `workflow.maxParallelWorkers`; waiting parents do not use those
+child slots. Cancelling or finishing a parent stops its children and releases
+their file claims. Full reports are saved under `.pi/bot-lobby/delegations/`.
+
+Active task steps show the parent and active worker children, for example
+**Step 6 – Implement large feature (6 devs working)**. Queued and finished agents
+are excluded. A child finishing does not complete a checklist step.
+
+The oracle, agents and children compact at settled turn boundaries before context
+reaches 250,000 estimated tokens, or earlier at 80% of the model window or Pi's
+native reserve threshold. Recent messages and summaries retain unfinished work;
+raw session history remains available. A failed summary leaves context intact.
+The boundary gives headroom below 300,000 tokens; a single very large input or tool
+result can temporarily exceed it before the next boundary.
+
+Pi's native MCP, `tool_search` and `codemode` are available. **MCP tools** in each
+agent's Settings entry grants exact tool names, one per line, such as
+`mcp__github__get_issue`. In `config.json` the same field is `mcpTools: ["mcp__github__get_issue"]`
+on `master`, `agents.backend`, `agents.designer`, `agents.qa`, `scout`, `researcher`,
+`quickFix` and `planner`. Grants default to empty and children inherit them.
+Read-only roles also require the server's `readOnlyHint: true`; hidden tools and
+ungranted calls are blocked, including calls nested inside codemode. Configure
+server connections through Pi's native MCP settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.33",
+  "version": "0.6.35",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",
@@ -46,16 +46,16 @@
     "test": "node --test --test-reporter=dot test/*.test.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": ">=1.0.1 <1.1.0",
+    "@earendil-works/pi-coding-agent": ">=1.0.1 <1.1.0",
+    "@earendil-works/pi-tui": ">=1.0.1 <1.1.0",
     "typebox": "*"
   },
   "devDependencies": {
     "@axe-core/playwright": "4.13.0",
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-ai": "1.0.1",
+    "@earendil-works/pi-coding-agent": "1.0.1",
+    "@earendil-works/pi-tui": "1.0.1",
     "@fontsource-variable/inter": "5.3.0",
     "@playwright/test": "1.62.0",
     "@tailwindcss/vite": "4.3.3",

package/src/desk/client-extension.ts

@@ -42,8 +42,8 @@ export function registerDeskClient(pi: ExtensionAPI, client?: DeskClient): void
     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;
+    // A vanished coordinator must not let an orphaned worker edit shared files.
+    if (answer.ok && answer.allowed) return undefined;
     return { block: true, reason: 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";
+export type DeskOp = "hello" | "check" | "claim" | "handover" | "mine" | "wait" | "delegate" | "cancel_delegate";
 
 export interface DeskRequest {
   id: number;
@@ -17,6 +17,7 @@ export interface DeskRequest {
   op: DeskOp;
   path?: string;
   intent?: string;
+  briefs?: string[];
   note?: string;
   timeoutMs?: number;
 }
@@ -79,12 +80,12 @@ function serve(socket: Socket, handler: DeskHandler): void {
 }
 
 /** Start a desk server on a fresh private socket. */
-export async function startDeskServer(handler: DeskHandler): Promise<DeskServer> {
+export async function startDeskServer(handler: DeskHandler, onDisconnect?: () => void): Promise<DeskServer> {
   const address = socketAddress();
   const sockets = new Set<Socket>();
   const server = createServer((socket) => {
     sockets.add(socket);
-    socket.on("close", () => sockets.delete(socket));
+    socket.on("close", () => { sockets.delete(socket); onDisconnect?.(); });
     serve(socket, handler);
   });
   await new Promise<void>((done, fail) => {

package/src/desk/session.ts

@@ -63,6 +63,12 @@ export interface DeskSessionOptions {
 }
 
 /** Master-side desk for one batch of parallel workers. */
+const sessions = new Map<string, DeskSession>();
+
+export function deskSessionAt(address: string): DeskSession | undefined {
+  return sessions.get(address);
+}
+
 export class DeskSession {
   readonly desk: FileDesk;
   private server?: DeskServer;
@@ -77,6 +83,7 @@ export class DeskSession {
 
   async open(): Promise<void> {
     this.server = await startDeskServer((request) => this.handle(request));
+    sessions.set(this.server.address, this);
   }
 
   /** Environment that points one worker's pi process at this desk. */
@@ -97,8 +104,13 @@ export class DeskSession {
 
   /** 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.releaseFiles(worker, note);
     this.handles.delete(worker);
+  }
+
+  /** 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 });
     for (const handover of this.desk.release(worker, note)) this.options.onHandover?.(handover);
   }
 
@@ -107,6 +119,7 @@ export class DeskSession {
   }
 
   async close(): Promise<void> {
+    if (this.server) sessions.delete(this.server.address);
     this.desk.close();
     await this.server?.close();
     this.server = undefined;

package/src/execution/agent-runner.ts

@@ -1,12 +1,12 @@
+import { randomUUID } from "node:crypto";
+import { createLiveRun } from "./live-run.ts";
 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 { activityDetail, activityWord, describeToolCall } from "../pi/activity.ts";
-import { shortDuration, truncate } from "../text.ts";
 import { EditLog } from "../state/changes.ts";
 import { formatMinutes, REPORT_GRACE_MS } from "../state/budget.ts";
-import { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner, type RelayAsk } from "./pi-runner.ts";
+import { runPiAgent, spawnPiProcess, type ProcessRunner, type RelayAsk } from "./pi-runner.ts";
 import { ASK_ENV } from "../ask/relay.ts";
 import { ASK_TOOL } from "../ask/types.ts";
 import { agentOfRun, grantOption } from "../excalidraw/sessions.ts";
@@ -40,6 +40,8 @@ export interface AgentRequest {
   /** Prompt layers selected for this run. */
   context: AgentContext;
   model?: string;
+  mcpTools?: string[];
+  delegationQuota?: { used: number };
   thinking?: string;
   timeoutMs: number;
   cwd: string;
@@ -140,8 +142,9 @@ export async function runAgent(request: AgentRequest, run: ProcessRunner = spawn
   // A failed attempt may have edited files before the retry: the run owns every edit.
   const edits = new EditLog(request.cwd);
   let last: AgentRun | undefined;
+  const quota = request.delegationQuota ??= { used: 0 };
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    last = await runAgentOnce(request, run, attempt, startedAt, edits);
+    last = await runAgentOnce(request, run, attempt, startedAt, edits, quota);
     request.onAttemptEnd?.(last);
     if (!retryable(last)) break;
     // Under a budget a retry only uses what is left of the allotment.
@@ -187,8 +190,8 @@ function toolsFor(request: AgentRequest): readonly string[] | undefined {
  * 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.
  */
-async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt: number, startedAt: string, edits: EditLog): Promise<AgentRun> {
-  const base = baseRun(request, `${request.taskId}:${request.domain}:${request.role}:${Date.now().toString(36)}`, startedAt, attempt);
+async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt: number, startedAt: string, edits: EditLog, quota: { used: number }): Promise<AgentRun> {
+  const base = baseRun(request, `${request.taskId}:${request.domain}:${request.role}:${randomUUID()}`, startedAt, attempt);
   request.onUpdate?.(base);
   const live = createLiveRun(base, request, edits);
 
@@ -203,6 +206,13 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
     const onTimeUp = time?.onTimeUp;
     const result = await runPiAgent({
       cwd: request.cwd,
+      agent: { runId: base.runId, taskId: request.taskId, domain: request.domain, role: request.role },
+      delegationQuota: quota,
+      onChildRun: (child) => {
+        for (const path of child.edited ?? []) edits.note("edit", { path });
+        request.onUpdate?.(child);
+      },
+      mcpTools: request.mcpTools,
       task: request.instruction,
       systemPrompt,
       tools: toolsFor(request),
@@ -270,92 +280,6 @@ function describeError(error: string, current: AgentRun, stalled: boolean): stri
   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, edits: EditLog) {
-  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": {
-        edits.note(event.toolName, event.args);
-        const activity = activityWord(event.toolName);
-        const detail = activityDetail(event.toolName, event.args);
-        const step = describeToolCall(event.toolName, event.args);
-        emit({ activity, detail, step, tools: (state.tools ?? 0) + 1 }, changed(activity, detail) || step !== state.step);
-        return;
-      }
-      case "thought":
-        emit({ thought: event.text }, true);
-        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 "time_up":
-        emit({ note: request.time?.onTimeUp ? "out of time: reporting where it left off" : "out of time: reporting", noteKind: "warning" }, true);
-        return;
-      case "extended":
-        emit({ endsAt: request.time?.endsAt, extendedMs: (state.extendedMs ?? 0) + event.ms }, true);
-        return;
-      case "asking":
-        emit({ note: `waiting on you: ${event.questions} question${event.questions === 1 ? "" : "s"}`, noteKind: "info" }, true);
-        return;
-      case "answered":
-        // Its time waited with it.
-        if (request.time) request.time.endsAt += event.waitedMs;
-        emit({ note: "you answered; carrying on", noteKind: "info", ...(request.time ? { endsAt: request.time.endsAt } : {}) }, 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[]> {
   const limit = Math.max(1, Math.min(concurrency, items.length));
   const results: TOut[] = new Array(items.length);

package/src/execution/delegation.ts

@@ -0,0 +1,193 @@
+import { toolsOf } from "../excalidraw/sessions.ts";
+import { appendMetrics, metricFromRun } from "../state/metrics.ts";
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import type { AgentRun } from "../schemas/findings.ts";
+import { agentProfile } from "../schemas/configuration.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";
+
+export const MAX_CHILDREN = 5;
+export const DELEGATE_TOOL = "delegate_subtasks";
+export const AGENT_ENV = "BOT_LOBBY_AGENT_POLICY";
+export const DELEGATION_ENV = "BOT_LOBBY_DELEGATION";
+
+/** 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> }>();
+
+async function inPool<T>(key: string, limit: number, signal: AbortSignal, work: () => Promise<T>): Promise<T> {
+  const pool = pools.get(key)!;
+  while (pool.active >= limit) {
+    signal.throwIfAborted();
+    await new Promise<void>((resolve, reject) => {
+      const wake = () => { signal.removeEventListener("abort", abort); resolve(); };
+      const abort = () => { pool.waiters = pool.waiters.filter((entry) => entry !== wake); reject(signal.reason); };
+      pool.waiters.push(wake);
+      signal.addEventListener("abort", abort, { once: true });
+    });
+  }
+  signal.throwIfAborted();
+  pool.active += 1;
+  try { return await work(); }
+  finally { pool.active -= 1; pool.waiters.shift()?.(); }
+}
+
+export function reserveChildren(quota: { used: number }, briefs: unknown): string[] {
+  if (!Array.isArray(briefs) || briefs.length === 0 || briefs.some((brief) => typeof brief !== "string" || !brief.trim() || brief.length > 32_000)) {
+    throw new Error("Provide non-empty self-contained briefs, each at most 32,000 characters.");
+  }
+  if (briefs.length > MAX_CHILDREN - quota.used) throw new Error(`Only ${MAX_CHILDREN - quota.used} of your five child slots remain.`);
+  quota.used += briefs.length;
+  return briefs.map((brief: string) => brief.trim());
+}
+
+export interface AgentPolicy {
+  tools: string[];
+  mcpTools: string[];
+  readOnly: boolean;
+  depth: number;
+}
+
+/** The host owns quotas, deadlines, file identities and child lifetimes, outside model context. */
+export async function delegationHost(options: PiRunOptions, run: ProcessRunner) {
+  const config = loadConfig();
+  const id = options.agent?.runId ?? randomUUID();
+  const baseTools = options.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+  const editable = baseTools.includes("edit") || baseTools.includes("write");
+  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, ...(options.excalidraw ? toolsOf(options.excalidraw) : []), "codemode", "tool_search", ...(depth === 1 ? [DELEGATE_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, 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[] };
+
+  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 controller = new AbortController();
+  const lifetime = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+  let timeController = new AbortController();
+  const childSignal = () => AbortSignal.any([lifetime, timeController.signal]);
+  const key = `${options.cwd}:${agent.taskId}`;
+  const pool = pools.get(key) ?? { active: 0, users: 0, waiters: [] };
+  pool.users += 1;
+  pools.set(key, pool);
+  let deadlineAt = Date.now() + (options.time?.upAtMs ?? options.timeoutMs);
+  let deadline = setTimeout(() => timeController.abort(), Math.max(1, deadlineAt - Date.now()));
+  const children = new Map<string, AgentRun>();
+  const pending = new Set<Promise<AgentRun>>();
+  const parentDeskId = options.env?.[DESK_ENV.worker] ?? id;
+  const update = (child: AgentRun) => {
+    children.set(child.runId, child);
+    options.onChildRun?.(child);
+    if (child.status === "running") return;
+    // Keep full child reports outside the parent's bounded tool result, including lobby jobs.
+    const root = detectProjectRoot(options.cwd, CONFIG_DIR_NAME);
+    const folder = join(dataRoot(root, CONFIG_DIR_NAME), "delegations");
+    mkdirSync(folder, { recursive: true });
+    writeFileSync(join(folder, `${child.runId}.json`), `${JSON.stringify(child)}\n`);
+    if (!options.agent || options.agent.taskId === options.agent.runId) appendMetrics(root, CONFIG_DIR_NAME, [metricFromRun(child)]);
+  };
+
+  const childRun = async (brief: string, signal: AbortSignal): Promise<AgentRun> => {
+    const childId = randomUUID();
+    const base: AgentRun = { runId: childId, parentRunId: id, depth: 2, taskId: agent.taskId, domain: agent.domain, role: agent.role, instruction: brief, stepInstruction: options.task, status: "running", output: "", attempts: 1, startedAt: new Date().toISOString(), ...(options.thinking ? { thinking: options.thinking } : {}) };
+    const edits = new EditLog(options.cwd);
+    const live = createLiveRun(base, { onUpdate: update, timeoutMs: options.timeoutMs }, edits);
+    update(base);
+    try {
+      const left = deadlineAt - Date.now();
+      if (left <= 0) throw new Error("The parent's time is up.");
+      const result = await runPiAgent({
+        ...options,
+        agent: { ...agent, runId: childId, depth: 2 },
+        task: brief,
+        tools: [...new Set([...tools.filter((tool) => tool !== DELEGATE_TOOL), ...(desk ? DESK_TOOLS : [])])],
+        mcpTools,
+        timeoutMs: left,
+        signal,
+        time: undefined,
+        wrapUpAtMs: Math.floor(left * 0.85),
+        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 }),
+      }, run);
+      const final: AgentRun = { ...live.current(), ...result, edited: edits.list(), finishedAt: new Date().toISOString(), note: undefined, noteKind: undefined };
+      update(final);
+      return final;
+    } catch (error) {
+      const final: AgentRun = { ...live.current(), edited: edits.list(), status: signal.aborted ? "cancelled" : "failed", error: (error as Error).message, finishedAt: new Date().toISOString() };
+      update(final);
+      return final;
+    } finally {
+      desk?.release(childId, () => "Child finished; re-read the file and check its report before continuing.");
+    }
+  };
+
+  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 !== "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.");
+    const runs = briefs.map((brief) => {
+      const promise = inPool(key, Math.max(1, config.workflow.maxParallelWorkers), signal, () => childRun(brief, signal));
+      pending.add(promise);
+      void promise.finally(() => pending.delete(promise)).catch(() => {});
+      return promise;
+    });
+    const results = await Promise.all(runs);
+    return { ok: true, text: JSON.stringify(results.map((child) => ({ runId: child.runId, status: child.status, report: child.output.slice(0, 12_000), reportPath: join(dataRoot(detectProjectRoot(options.cwd, CONFIG_DIR_NAME), CONFIG_DIR_NAME), "delegations", `${child.runId}.json`), error: child.error, usage: child.usage }))) };
+  }, () => controller.abort()).catch(async (error) => {
+    clearTimeout(deadline);
+    if (ownedDesk) await ownedDesk.close();
+    pool.users -= 1;
+    if (pool.users === 0) pools.delete(key);
+    throw error;
+  });
+
+  let closed = false;
+  return {
+    tools: desk ? [...new Set([...tools, ...DESK_TOOLS])] : tools,
+    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: `For substantial, separable work, use ${DELEGATE_TOOL} with complete briefs (goal, files, contracts, constraints, done criteria). You have at most five children total; children cannot delegate. 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." : ""}`,
+    onStart: (handle: Parameters<NonNullable<PiRunOptions["onStart"]>>[0]) => {
+      desk?.attach(parentDeskId, { runId: id, steer: handle.steer, annotate: () => {} });
+      options.onStart?.(handle);
+    },
+    get children() { return [...children.values()]; },
+    pause() { clearTimeout(deadline); },
+    extend(ms: number, reset = false) {
+      deadlineAt = reset ? Date.now() + ms : deadlineAt + ms;
+      clearTimeout(deadline);
+      if (timeController.signal.aborted) timeController = new AbortController();
+      deadline = setTimeout(() => timeController.abort(), Math.max(1, deadlineAt - Date.now()));
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      controller.abort();
+      clearTimeout(deadline);
+      await Promise.allSettled([...pending]);
+      await server.close();
+      if (ownedDesk) { desk?.release(parentDeskId, () => "Parent finished; re-read before editing."); await ownedDesk.close(); }
+      pool.users -= 1;
+      if (pool.users === 0) pools.delete(key);
+    },
+  };
+}

package/src/execution/live-run.ts

@@ -0,0 +1,95 @@
+import type { AgentRequest, LivePatch } from "./agent-runner.ts";
+import type { AgentRun } from "../schemas/findings.ts";
+import type { PiStreamEvent } from "./pi-runner.ts";
+import { EditLog } from "../state/changes.ts";
+import { activityDetail, activityWord, describeToolCall } from "../pi/activity.ts";
+import { shortDuration, truncate } from "../text.ts";
+
+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.
+ */
+export function createLiveRun(base: AgentRun, request: Pick<AgentRequest, "onUpdate" | "timeoutMs" | "time">, edits: EditLog) {
+  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": {
+        edits.note(event.toolName, event.args);
+        const activity = activityWord(event.toolName);
+        const detail = activityDetail(event.toolName, event.args);
+        const step = describeToolCall(event.toolName, event.args);
+        emit({ activity, detail, step, tools: (state.tools ?? 0) + 1 }, changed(activity, detail) || step !== state.step);
+        return;
+      }
+      case "thought":
+        emit({ thought: event.text }, true);
+        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 "compaction_end":
+        emit({ note: event.error, noteKind: event.error ? "warning" : undefined }, true);
+        return;
+      case "wrap_up":
+        emit({ note: `asked to wrap up (${shortDuration(request.timeoutMs)} limit)`, noteKind: "warning", wrappedUp: true }, true);
+        return;
+      case "time_up":
+        emit({ note: request.time?.onTimeUp ? "out of time: reporting where it left off" : "out of time: reporting", noteKind: "warning" }, true);
+        return;
+      case "extended":
+        emit({ endsAt: request.time?.endsAt, extendedMs: (state.extendedMs ?? 0) + event.ms }, true);
+        return;
+      case "asking":
+        emit({ note: `waiting on you: ${event.questions} question${event.questions === 1 ? "" : "s"}`, noteKind: "info" }, true);
+        return;
+      case "answered":
+        // Its time waited with it.
+        if (request.time) request.time.endsAt += event.waitedMs;
+        emit({ note: "you answered; carrying on", noteKind: "info", ...(request.time ? { endsAt: request.time.endsAt } : {}) }, 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]!;
+}