little-coder 1.8.4 → 1.9.0

package/.pi/extensions/subagent/live-spawn.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { resolve } from "node:path";
+import { runSubCoder, runSubCodersConcurrent } from "./spawn.ts";
+
+// Live end-to-end: spawns real child little-coder sessions against the local
+// model. Skipped unless LC_LIVE=1 (needs a running model server). Run with:
+//   LC_LIVE=1 LLAMACPP_API_KEY=noop npx vitest run .pi/extensions/subagent/live-spawn.test.ts
+const LIVE = process.env.LC_LIVE === "1";
+const MODEL = process.env.LC_LIVE_MODEL || "llamacpp/qwen3.6-35b-a3b";
+const repoRoot = resolve(__dirname, "..", "..", "..");
+
+describe.skipIf(!LIVE)("sub-coder live spawn", () => {
+  it(
+    "spawns a child that runs on the parent's model and returns a report",
+    async () => {
+      const r = await runSubCoder({
+        id: "1",
+        label: "ping",
+        task: "Respond with exactly the single word ALIVE. Do not use any tools.",
+        cwd: repoRoot,
+        model: MODEL,
+      });
+      expect(r.exitCode).toBe(0);
+      expect(r.report.toUpperCase()).toContain("ALIVE");
+      expect(r.usage.turns).toBeGreaterThan(0);
+    },
+    240_000,
+  );
+
+  it(
+    "runs two sub-coders in parallel and reports per-item",
+    async () => {
+      const results = await runSubCodersConcurrent(
+        [
+          { id: "1", label: "two", task: "What is 2+2? Reply with just the number.", cwd: repoRoot },
+          { id: "2", label: "cap", task: "What is the capital of France? One word.", cwd: repoRoot },
+        ],
+        { model: MODEL },
+      );
+      expect(results).toHaveLength(2);
+      expect(results.every((r) => r.exitCode === 0)).toBe(true);
+      expect(results[0].report).toContain("4");
+      expect(results[1].report.toLowerCase()).toContain("paris");
+    },
+    300_000,
+  );
+});

package/.pi/extensions/subagent/spawn.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildChildEnv,
+  defaultConcurrency,
+  getFinalText,
+  resolveLauncher,
+  summarizeActivity,
+  truncateReport,
+  SUBCODER_ALLOWED_TOOLS,
+  type SubCoderResult,
+} from "./spawn.ts";
+
+const base: SubCoderResult = {
+  id: "1",
+  label: "x",
+  task: "t",
+  exitCode: -1,
+  report: "",
+  messages: [],
+  stderr: "",
+  usage: { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 },
+};
+
+describe("getFinalText", () => {
+  it("returns the last assistant text block", () => {
+    const messages = [
+      { role: "assistant", content: [{ type: "text", text: "first" }] },
+      { role: "assistant", content: [{ type: "toolCall", name: "read", arguments: {} }] },
+      { role: "assistant", content: [{ type: "text", text: "final answer" }] },
+    ];
+    expect(getFinalText(messages)).toBe("final answer");
+  });
+  it("returns empty string when there is no assistant text", () => {
+    expect(getFinalText([{ role: "user", content: [{ type: "text", text: "hi" }] }])).toBe("");
+    expect(getFinalText([])).toBe("");
+  });
+});
+
+describe("truncateReport", () => {
+  it("leaves short reports intact", () => {
+    expect(truncateReport("short")).toBe("short");
+  });
+  it("truncates long reports with a notice", () => {
+    const out = truncateReport("a".repeat(5000), 100);
+    expect(out.length).toBeLessThan(300);
+    expect(out).toContain("truncated at 100 chars");
+  });
+});
+
+describe("summarizeActivity", () => {
+  it("shows the report's first line when done", () => {
+    expect(summarizeActivity({ ...base, exitCode: 0, report: "Found 3 routes\nmore" })).toBe("Found 3 routes");
+  });
+  it("surfaces the latest tool call while running", () => {
+    const r = {
+      ...base,
+      messages: [{ role: "assistant", content: [{ type: "toolCall", name: "grep", arguments: { pattern: "login(" } }] }],
+    };
+    expect(summarizeActivity(r)).toBe("→ grep login(");
+  });
+  it("shows the error message on failure", () => {
+    expect(summarizeActivity({ ...base, exitCode: 1, errorMessage: "boom" })).toBe("boom");
+  });
+  it("falls back to working when running with no tool call", () => {
+    expect(summarizeActivity(base)).toBe("working…");
+  });
+});
+
+describe("buildChildEnv", () => {
+  it("constrains the child to read-only tools and the headless fast-path", () => {
+    const env = buildChildEnv();
+    expect(env.LITTLE_CODER_ALLOWED_TOOLS).toBe(SUBCODER_ALLOWED_TOOLS);
+    expect(env.LITTLE_CODER_ALLOWED_TOOLS).not.toContain("edit");
+    expect(env.LITTLE_CODER_ALLOWED_TOOLS).not.toContain("write");
+    expect(env.LITTLE_CODER_ALLOWED_TOOLS).not.toContain("dispatch");
+    expect(env.LITTLE_CODER_PERMISSION_MODE).toBe("auto");
+    expect(env.LITTLE_CODER_SUBAGENT).toBe("1");
+  });
+  it("merges extra overrides", () => {
+    expect(buildChildEnv({ FOO: "bar" }).FOO).toBe("bar");
+  });
+});
+
+describe("resolveLauncher / defaultConcurrency", () => {
+  it("points at bin/little-coder.mjs", () => {
+    expect(resolveLauncher().replace(/\\/g, "/")).toMatch(/\/bin\/little-coder\.mjs$/);
+  });
+  it("defaults concurrency to 2", () => {
+    const prev = process.env.LITTLE_CODER_SUBCODER_CONCURRENCY;
+    delete process.env.LITTLE_CODER_SUBCODER_CONCURRENCY;
+    expect(defaultConcurrency()).toBe(2);
+    process.env.LITTLE_CODER_SUBCODER_CONCURRENCY = "3";
+    expect(defaultConcurrency()).toBe(3);
+    if (prev === undefined) delete process.env.LITTLE_CODER_SUBCODER_CONCURRENCY;
+    else process.env.LITTLE_CODER_SUBCODER_CONCURRENCY = prev;
+  });
+});

package/.pi/extensions/subagent/spawn.ts

@@ -0,0 +1,373 @@
+// Sub-coder spawn engine.
+//
+// A "sub-coder" is a child little-coder session with an isolated context window,
+// spawned to research a focused question (read the repo + browse online) and
+// report back concisely. Both the `dispatch` tool (index.ts) and Plan Mode
+// (../plan-mode) drive children through this module.
+//
+// Why spawn little-coder's OWN launcher and not bare `pi`: the child must use
+// the same local-model provider, the same extensions, and the same AGENTS.md as
+// the parent. The launcher (bin/little-coder.mjs) is what composes all of that —
+// it registers the provider (llama-cpp-provider), wires every .pi/extension, and
+// passes --system-prompt AGENTS.md. Spawning `pi` directly would yield a blank
+// agent with none of it. We therefore re-invoke the launcher headless
+// (--mode json -p --no-session) and parse pi's JSON event stream from stdout.
+//
+// The child is constrained to read + browse (no edit/write, no recursive
+// dispatch) entirely through environment variables the existing gates already
+// honor — see buildChildEnv().
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Tools a sub-coder may use: read + search + browse online + read-only bash.
+// Enforced by the tool-gating extension in the child. Deliberately omits
+// edit/write (children never mutate the tree) and `dispatch` (no fan-out bombs).
+export const SUBCODER_ALLOWED_TOOLS = [
+  "read",
+  "grep",
+  "glob",
+  "find",
+  "ls",
+  "bash",
+  "webfetch",
+  "websearch",
+  "BrowserNavigate",
+  "BrowserClick",
+  "BrowserType",
+  "BrowserScroll",
+  "BrowserExtract",
+  "BrowserBack",
+  "BrowserHistory",
+].join(",");
+
+// Appended to every task so children answer with a short, parent-friendly
+// report rather than a wall of pasted file contents.
+export const REPORT_SUFFIX =
+  "\n\nWhen done, reply with a CONCISE report (≤ ~200 words): the key findings, " +
+  "file:line citations where relevant, and a direct answer to the task. Do NOT " +
+  "paste large file contents or long logs — summarize them.";
+
+export const MAX_REPORT_CHARS = 2000;
+
+export interface SubCoderUsage {
+  input: number;
+  output: number;
+  cost: number;
+  turns: number;
+  contextTokens: number;
+}
+
+export interface SubCoderResult {
+  id: string;
+  label: string;
+  task: string;
+  /** -1 = still running, 0 = ok, >0 = failed. */
+  exitCode: number;
+  /** The child's final assistant text — the report shown to the parent model. */
+  report: string;
+  /** Full child transcript. UI-only (rendered in tool details); never sent to the parent model. */
+  messages: any[];
+  stderr: string;
+  usage: SubCoderUsage;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+function emptyUsage(): SubCoderUsage {
+  return { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 };
+}
+
+// .pi/extensions/subagent/spawn.ts → up 3 → package root → bin/little-coder.mjs.
+// Same path math as branding/index.ts; works in the local checkout and the
+// installed npm layout.
+export function resolveLauncher(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, "..", "..", "..", "bin", "little-coder.mjs");
+}
+
+export function buildChildEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    // Constrain the child to read + browse, no mutation, no recursion.
+    LITTLE_CODER_ALLOWED_TOOLS: SUBCODER_ALLOWED_TOOLS,
+    // bash limited to permission-gate's read-only BUILTIN_SAFE_PREFIXES.
+    LITTLE_CODER_PERMISSION_MODE: "auto",
+    // Headless fast-path in the launcher (skip update-check + settings write).
+    LITTLE_CODER_SUBAGENT: "1",
+    // Belt and suspenders: never show pi's update banner in a child.
+    PI_SKIP_VERSION_CHECK: "1",
+    ...extra,
+  };
+}
+
+export function defaultConcurrency(): number {
+  const n = Number(process.env.LITTLE_CODER_SUBCODER_CONCURRENCY);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 2;
+}
+
+/** The last assistant text block in a transcript — the child's report. */
+export function getFinalText(messages: any[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m?.role === "assistant" && Array.isArray(m.content)) {
+      for (const part of m.content) {
+        if (part?.type === "text" && typeof part.text === "string" && part.text.trim()) {
+          return part.text;
+        }
+      }
+    }
+  }
+  return "";
+}
+
+export function truncateReport(text: string, max = MAX_REPORT_CHARS): string {
+  const t = (text ?? "").trim();
+  if (t.length <= max) return t;
+  return `${t.slice(0, max).trimEnd()}\n\n… (report truncated at ${max} chars — full transcript in tool details)`;
+}
+
+/** A one-line "what is this child doing right now" string for the tracker. */
+export function summarizeActivity(r: SubCoderResult): string {
+  if (r.exitCode === 0) {
+    const firstLine = r.report.split(/\r?\n/).find((l) => l.trim()) ?? "(done)";
+    return firstLine.length > 56 ? `${firstLine.slice(0, 55)}…` : firstLine;
+  }
+  if (r.exitCode > 0) return r.errorMessage || r.stderr.split(/\r?\n/)[0] || "(failed)";
+  // running: surface the most recent tool call, else the latest partial text.
+  for (let i = r.messages.length - 1; i >= 0; i--) {
+    const m = r.messages[i];
+    if (m?.role === "assistant" && Array.isArray(m.content)) {
+      for (let j = m.content.length - 1; j >= 0; j--) {
+        const part = m.content[j];
+        if (part?.type === "toolCall") {
+          const a = part.arguments ?? {};
+          const hint = a.pattern || a.query || a.url || a.path || a.file_path || a.command || "";
+          return `→ ${part.name}${hint ? ` ${String(hint).slice(0, 40)}` : ""}`;
+        }
+      }
+    }
+  }
+  return "working…";
+}
+
+export interface RunSubCoderOptions {
+  id: string;
+  label: string;
+  task: string;
+  cwd: string;
+  /** "provider/id" of the parent's model, so the child uses the same one. */
+  model?: string;
+  signal?: AbortSignal;
+  /** Called whenever the child emits a new message, with the live result. */
+  onUpdate?: (r: SubCoderResult) => void;
+}
+
+/** Run one sub-coder to completion. Never throws — failures land in exitCode/stderr. */
+export async function runSubCoder(opts: RunSubCoderOptions): Promise<SubCoderResult> {
+  const result: SubCoderResult = {
+    id: opts.id,
+    label: opts.label,
+    task: opts.task,
+    exitCode: -1,
+    report: "",
+    messages: [],
+    stderr: "",
+    usage: emptyUsage(),
+  };
+
+  const launcher = resolveLauncher();
+  if (!existsSync(launcher)) {
+    result.exitCode = 1;
+    result.stderr = `sub-coder launcher not found at ${launcher}`;
+    result.errorMessage = result.stderr;
+    opts.onUpdate?.(result);
+    return result;
+  }
+
+  const args = [
+    launcher,
+    "--no-update-check",
+    "--mode",
+    "json",
+    "-p",
+    "--no-session",
+    // Match the parent's model so children run on the same backend. Without
+    // this the child would fall back to pi's default model.
+    ...(opts.model ? ["--model", opts.model] : []),
+    opts.task + REPORT_SUFFIX,
+  ];
+
+  const emit = () => {
+    result.report = getFinalText(result.messages);
+    opts.onUpdate?.(result);
+  };
+
+  const exitCode = await new Promise<number>((resolveP) => {
+    let proc;
+    try {
+      proc = spawn(process.execPath, args, {
+        cwd: opts.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: buildChildEnv(),
+      });
+    } catch (e) {
+      result.stderr += String((e as Error)?.message ?? e);
+      resolveP(1);
+      return;
+    }
+
+    let buffer = "";
+    const processLine = (line: string) => {
+      if (!line.trim()) return;
+      let ev: any;
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        return; // non-JSON noise (shouldn't happen in --mode json, but be safe)
+      }
+      if (ev.type === "message_end" && ev.message) {
+        const msg = ev.message;
+        result.messages.push(msg);
+        if (msg.role === "assistant") {
+          result.usage.turns++;
+          const u = msg.usage;
+          if (u) {
+            result.usage.input += u.input || 0;
+            result.usage.output += u.output || 0;
+            result.usage.cost += u.cost?.total || 0;
+            result.usage.contextTokens = u.totalTokens || 0;
+          }
+          if (msg.stopReason) result.stopReason = msg.stopReason;
+          if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+        }
+        emit();
+      } else if (ev.type === "tool_result_end" && ev.message) {
+        result.messages.push(ev.message);
+        emit();
+      }
+    };
+
+    proc.stdout.on("data", (d) => {
+      buffer += d.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() || "";
+      for (const l of lines) processLine(l);
+    });
+    proc.stderr.on("data", (d) => {
+      result.stderr += d.toString();
+    });
+    proc.on("close", (code) => {
+      if (buffer.trim()) processLine(buffer);
+      resolveP(code ?? 0);
+    });
+    proc.on("error", (e) => {
+      result.stderr += String(e?.message ?? e);
+      resolveP(1);
+    });
+
+    if (opts.signal) {
+      const kill = () => {
+        try {
+          proc.kill("SIGTERM");
+        } catch {
+          /* already gone */
+        }
+        setTimeout(() => {
+          try {
+            if (!proc.killed) proc.kill("SIGKILL");
+          } catch {
+            /* ignore */
+          }
+        }, 4000);
+      };
+      if (opts.signal.aborted) kill();
+      else opts.signal.addEventListener("abort", kill, { once: true });
+    }
+  });
+
+  result.exitCode = exitCode;
+  result.report = getFinalText(result.messages);
+  if (exitCode !== 0 && !result.errorMessage) {
+    result.errorMessage = result.stderr.split(/\r?\n/).filter(Boolean).slice(-1)[0] || `exited ${exitCode}`;
+  }
+  return result;
+}
+
+export interface SubCoderItem {
+  id: string;
+  label: string;
+  task: string;
+  cwd: string;
+}
+
+async function mapWithConcurrencyLimit<TIn, TOut>(
+  items: TIn[],
+  concurrency: number,
+  fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+  if (items.length === 0) return [];
+  const limit = Math.max(1, Math.min(concurrency, items.length));
+  const results: TOut[] = new Array(items.length);
+  let next = 0;
+  const workers = new Array(limit).fill(null).map(async () => {
+    while (true) {
+      const cur = next++;
+      if (cur >= items.length) return;
+      results[cur] = await fn(items[cur], cur);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Run several sub-coders with a concurrency cap (default 2 — a single local
+ * backend is easily starved). `onUpdate` receives a fresh snapshot of all
+ * results whenever any child changes, which drives the live tracker.
+ */
+export async function runSubCodersConcurrent(
+  items: SubCoderItem[],
+  opts: {
+    signal?: AbortSignal;
+    concurrency?: number;
+    model?: string;
+    onUpdate?: (all: SubCoderResult[]) => void;
+  } = {},
+): Promise<SubCoderResult[]> {
+  const all: SubCoderResult[] = items.map((it) => ({
+    id: it.id,
+    label: it.label,
+    task: it.task,
+    exitCode: -1,
+    report: "",
+    messages: [],
+    stderr: "",
+    usage: emptyUsage(),
+  }));
+  const snapshot = () => opts.onUpdate?.(all.map((r) => ({ ...r })));
+  snapshot();
+
+  await mapWithConcurrencyLimit(items, opts.concurrency ?? defaultConcurrency(), async (it, i) => {
+    const r = await runSubCoder({
+      id: it.id,
+      label: it.label,
+      task: it.task,
+      cwd: it.cwd,
+      model: opts.model,
+      signal: opts.signal,
+      onUpdate: (live) => {
+        all[i] = live;
+        snapshot();
+      },
+    });
+    all[i] = r;
+    snapshot();
+    return r;
+  });
+
+  return all;
+}

package/.pi/extensions/subagent/tracker.ts

@@ -0,0 +1,139 @@
+// Live sub-coder tracker — a small animated panel above the input showing each
+// running/finished sub-coder, its status, elapsed time and current activity.
+//
+// Driven by string[] content re-set on a timer (the spinner + clock need to
+// tick, which event updates alone can't do). Colors are raw 24-bit/SGR escapes
+// (same approach as branding's honey accent) so the panel doesn't depend on the
+// active theme and the string[] form of setWidget can be used directly.
+
+import { summarizeActivity, type SubCoderResult } from "./spawn.ts";
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+// Brand honey (matches branding/index.ts) + plain SGR status colors.
+const honey = (s: string) => `\x1b[38;2;225;90;31m${s}\x1b[39m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[39m`;
+const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
+const gray = (s: string) => `\x1b[90m${s}\x1b[39m`;
+
+function fmtElapsed(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const m = Math.floor(total / 60);
+  const s = total % 60;
+  return `${m}:${s.toString().padStart(2, "0")}`;
+}
+
+function padEnd(s: string, n: number): string {
+  return s.length >= n ? s : s + " ".repeat(n - s.length);
+}
+
+export interface TrackerUI {
+  hasUI: boolean;
+  ui: {
+    setWidget: (
+      key: string,
+      content: string[] | undefined,
+      options?: { placement?: "aboveEditor" | "belowEditor" },
+    ) => void;
+  };
+}
+
+export class SubCoderTracker {
+  private readonly key: string;
+  private readonly placement: "aboveEditor" | "belowEditor";
+  private results = new Map<string, SubCoderResult>();
+  private order: string[] = [];
+  private startedAt = new Map<string, number>();
+  private finishedAt = new Map<string, number>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastFrame = "";
+
+  constructor(
+    private ctx: TrackerUI,
+    opts: { key?: string; placement?: "aboveEditor" | "belowEditor"; totalSince?: number } = {},
+  ) {
+    this.key = opts.key ?? "subcoders";
+    this.placement = opts.placement ?? "aboveEditor";
+    this.totalSince = opts.totalSince;
+  }
+
+  // When set, the header shows a running total-elapsed timer (the overall
+  // process time, not just per-sub-coder).
+  private totalSince?: number;
+
+  /** Register the items and start the animation timer. */
+  begin(items: { id: string; label: string }[]): void {
+    if (!this.ctx.hasUI || items.length === 0) return;
+    const now = Date.now();
+    for (const it of items) {
+      if (!this.startedAt.has(it.id)) {
+        this.order.push(it.id);
+        this.startedAt.set(it.id, now);
+        this.results.set(it.id, {
+          id: it.id,
+          label: it.label,
+          task: "",
+          exitCode: -1,
+          report: "",
+          messages: [],
+          stderr: "",
+          usage: { input: 0, output: 0, cost: 0, turns: 0, contextTokens: 0 },
+        });
+      }
+    }
+    this.render();
+    if (!this.timer) this.timer = setInterval(() => this.render(), 120);
+  }
+
+  /** Feed a fresh snapshot of all results (from runSubCodersConcurrent). */
+  update(results: SubCoderResult[]): void {
+    if (!this.ctx.hasUI) return;
+    const now = Date.now();
+    for (const r of results) {
+      if (!this.startedAt.has(r.id)) {
+        this.order.push(r.id);
+        this.startedAt.set(r.id, now);
+      }
+      this.results.set(r.id, r);
+      if (r.exitCode !== -1 && !this.finishedAt.has(r.id)) this.finishedAt.set(r.id, now);
+    }
+  }
+
+  /** Stop the timer, paint a final static frame, then clear the panel. */
+  end(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (!this.ctx.hasUI) return;
+    this.render();
+    this.ctx.ui.setWidget(this.key, undefined, { placement: this.placement });
+  }
+
+  private render(): void {
+    if (!this.ctx.hasUI || this.order.length === 0) return;
+    const now = Date.now();
+    const frame = SPINNER[Math.floor(now / 100) % SPINNER.length];
+
+    const items = this.order.map((id) => this.results.get(id)!).filter(Boolean);
+    const done = items.filter((r) => r.exitCode !== -1).length;
+    const labelWidth = Math.min(18, Math.max(...items.map((r) => r.label.length), 4));
+
+    const total = this.totalSince !== undefined ? ` · ${fmtElapsed(now - this.totalSince)}` : "";
+    const header = `${honey("sub-coders")} ${gray(`· ${done}/${items.length} done${total}`)}`;
+    const rows = items.map((r) => {
+      const running = r.exitCode === -1;
+      const icon = running ? honey(frame) : r.exitCode === 0 ? green("✓") : red("✗");
+      const end = this.finishedAt.get(r.id) ?? now;
+      const elapsed = fmtElapsed(end - (this.startedAt.get(r.id) ?? now));
+      const activity = summarizeActivity(r);
+      return `  ${icon} ${padEnd(r.label, labelWidth)}  ${gray(padEnd(elapsed, 5))}  ${gray(activity)}`;
+    });
+
+    const lines = [header, ...rows];
+    const frameKey = lines.join("\n");
+    if (frameKey === this.lastFrame) return; // diff-guard: skip identical repaints
+    this.lastFrame = frameKey;
+    this.ctx.ui.setWidget(this.key, lines, { placement: this.placement });
+  }
+}

package/AGENTS.md

@@ -11,6 +11,7 @@ Instead, proactively write the necessary background scripts (Python, Bash, etc.)
 # Runtime invariants
 
 - **Write refuses on existing files.** Use **Edit** with exact `old_string` / `new_string` to modify — `old_string` must match exactly (whitespace included). If it appears multiple times in the file, pass `replace_all: true` or add more surrounding context to make the match unique. Read with line numbers first when precision is in doubt. This is a runtime invariant, not guidance — when Write refuses, the error returns the exact Edit call-shape for the same path; follow it.
+- **Edit refuses on unread files.** A file must be **Read** in the current session before you can Edit it — this is a runtime invariant. If an edit is blocked, Read the file first to get the exact current text (so `old_string` matches), then Edit. Files you just wrote count as read.
 - **Bash / ShellSession default timeout is 30 s.** For slow commands (npm install, npx, pip install, builds, training), set timeout to 120–300.
 - Per-benchmark tools (`BrowserNavigate` / `Click` / `Type` / `Scroll` / `Extract` / `Back` / `History` and `EvidenceAdd` / `Get` / `List`) appear when relevant; their schemas are passed to you directly when available.
 
@@ -27,6 +28,10 @@ Instead, proactively write the necessary background scripts (Python, Bash, etc.)
 - **WebFetch**: Fetch and extract content from a URL
 - **WebSearch**: Search the web via DuckDuckGo
 
+## Delegation
+
+- **Dispatch**: Spawn isolated sub-coders to research a focused question. Each child reads the repo and browses online (read-only — no edit/write) and returns a concise report; the full transcript stays out of your context. Single mode `{ task }`, or parallel `{ tasks: [{ label, task }] }` (up to 4). Use it to gather facts before implementing, then do the edits yourself.
+
 Additional tools appear per benchmark: `BrowserNavigate`/`Click`/`Type`/`Scroll`/`Extract`/`Back`/`History` and `EvidenceAdd`/`Get`/`List` (GAIA). Their schemas are passed to you directly when available.
 
 # Approaching complex tasks