@a-t-h-i/bot-lobby 0.6.2 → 0.6.4

package/src/ask/tool.ts

@@ -0,0 +1,126 @@
+/**
+ * `ask_user_question`: the model asks instead of guessing, with typed options
+ * the user picks from (or answers in their own words). Registered by
+ * bot-lobby in every pi session it loads in, the lobby's or not, so pi needs
+ * no separate questionnaire extension. A subagent has no terminal: it gets
+ * the tool only when the master lets it ask (the designer), and its questions
+ * are relayed through the master (see relay.ts).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { isSubagentProcess } from "../pi/quiet.ts";
+import { askUser, type Asker } from "./dialog.ts";
+import { isImagePath } from "./image.ts";
+import { relayAsker, relayEnabled } from "./relay.ts";
+import { ASK_TOOL, MAX_HEADER, MAX_LABEL, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, RESERVED, type AskQuestion, type AskResult } from "./types.ts";
+
+export { ASK_TOOL };
+
+const OptionSchema = Type.Object({
+  label: Type.String({ maxLength: MAX_LABEL, description: `The option as the user sees and picks it: 1-5 words, at most ${MAX_LABEL} characters.` }),
+  description: Type.Optional(Type.String({ description: "What choosing it means: its trade-offs or consequences. Markdown." })),
+  preview: Type.Optional(Type.String({ description: "Markdown shown beside the options while this one is focused: a mockup, a code snippet, a diagram, a config. Only when seeing it helps the user compare." })),
+  image: Type.Optional(Type.String({ description: "Path to a PNG (or JPEG, GIF, WebP) shown with the preview: a screenshot or a rendered mockup of this option. Drawn as the image in terminals that can, as coloured blocks (PNG) elsewhere." })),
+});
+
+const QuestionSchema = Type.Object({
+  question: Type.String({ description: "The whole question, clear and specific, ending with a question mark. Markdown." }),
+  header: Type.String({ maxLength: MAX_HEADER, description: `A short chip naming the question (at most ${MAX_HEADER} characters), e.g. "Auth" or "Layout".` }),
+  options: Type.Array(OptionSchema, { minItems: MIN_OPTIONS, maxItems: MAX_OPTIONS, description: `${MIN_OPTIONS}-${MAX_OPTIONS} distinct options. Put the one you recommend first and end its label with "(Recommended)". The user can always answer in their own words instead.` }),
+  multiSelect: Type.Optional(Type.Boolean({ description: "True when several answers can apply together." })),
+});
+
+export const AskParams = Type.Object({
+  questions: Type.Array(QuestionSchema, { minItems: 1, maxItems: MAX_QUESTIONS, description: `1-${MAX_QUESTIONS} questions asked together.` }),
+});
+
+const DESCRIPTION = [
+  "Ask the user one to four questions with options to pick from, when the answer would change what you do and you would otherwise guess.",
+  "Each question has 2-4 options (the one you recommend first, its label ending in \"(Recommended)\"); the user can pick one (or several with multiSelect), or answer in their own words.",
+  "Questions, descriptions and previews are Markdown. Give options a `preview` when the user needs to see them to choose: a UI mockup, a layout sketch, a code snippet, a config; the focused option's preview shows beside the list. An option can also carry an `image` file (a screenshot, a rendered mockup).",
+  "Do not use it for yes/no confirmations of what you were already told to do, or for questions the conversation already answers.",
+].join(" ");
+
+const RELAYED = "Your questions reach the user through the oracle, and your clock stops while they answer. Ask only what is theirs to decide (a visual direction, a layout, a trade-off they care about), all at once; decide the rest yourself.";
+
+/** Why a set of questions cannot be asked as given, or undefined when it can. */
+export function invalidQuestions(questions: readonly AskQuestion[]): string | undefined {
+  const asked = new Set<string>();
+  for (const [index, question] of questions.entries()) {
+    const at = `question ${index + 1}`;
+    if (!question.question.trim()) return `${at} is empty`;
+    if (asked.has(question.question.trim().toLowerCase())) return `${at} repeats an earlier question`;
+    asked.add(question.question.trim().toLowerCase());
+    const labels = new Set<string>();
+    for (const option of question.options) {
+      const label = option.label.trim().toLowerCase();
+      if (!label) return `${at} has an option without a label`;
+      if (RESERVED.has(label)) return `${at}: "${option.label}" is kept for the user's own answer; leave it out`;
+      if (labels.has(label)) return `${at} has two options labelled "${option.label}"`;
+      if (option.image?.trim() && !isImagePath(option.image)) return `${at}: the image for "${option.label}" must be a .png, .jpg, .gif or .webp file`;
+      labels.add(label);
+    }
+  }
+  return undefined;
+}
+
+/** What the model reads back: each question with its answer, or that it was skipped. */
+export function answerSummary(questions: readonly AskQuestion[], result: AskResult): string {
+  if (result.cancelled && result.answers.length === 0) {
+    // A relay that could not ask anyone (auto mode) says why.
+    if (result.globalNote) return result.globalNote;
+    return "The user put the questions away without answering. Do not ask the same again right away: go on with your best judgement and say what you assumed, or ask something narrower.";
+  }
+  const lines = questions.map((question, index) => {
+    const answer = result.answers.find((entry) => entry.questionIndex === index);
+    const head = `${index + 1}. [${question.header}] ${question.question.replace(/\s+/g, " ").trim()}`;
+    if (!answer) return `${head}\n   → (not answered)`;
+    const text = answer.kind === "multi" ? (answer.selected ?? []).join(", ") : answer.answer ?? "";
+    return `${head}\n   → ${text}${answer.kind === "custom" ? " (in the user's own words)" : ""}${answer.notes ? `\n   note: ${answer.notes}` : ""}`;
+  });
+  return [
+    result.cancelled ? "The user answered some questions, then put the rest away:" : "The user answered:",
+    ...lines,
+    ...(result.globalNote ? ["", `Note: ${result.globalNote}`] : []),
+  ].join("\n");
+}
+
+/**
+ * Register `ask_user_question` in this pi session; in a subagent only when
+ * the master relays its questions. `ask` is swappable for tests.
+ */
+export function registerAskTool(pi: ExtensionAPI, ask?: Asker): void {
+  const subagent = isSubagentProcess();
+  if (subagent && !relayEnabled()) return;
+  const asker = ask ?? (subagent ? relayAsker : askUser);
+  pi.registerTool({
+    name: ASK_TOOL,
+    label: "Ask",
+    description: subagent ? `${DESCRIPTION} ${RELAYED}` : DESCRIPTION,
+    promptSnippet: "Ask the user structured questions with options (and previews) instead of guessing",
+    promptGuidelines: [
+      "Use ask_user_question when a real decision is the user's and the answer changes your work; batch related questions (at most four) into one call.",
+    ],
+    parameters: AskParams,
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const questions = (params as { questions: AskQuestion[] }).questions;
+      const invalid = invalidQuestions(questions);
+      if (invalid) throw new Error(`${invalid}.`);
+      const result = await asker(questions, ctx, signal);
+      return { content: [{ type: "text", text: answerSummary(questions, result) }], details: result };
+    },
+    renderCall(args, theme) {
+      const questions = (args as { questions?: AskQuestion[] }).questions ?? [];
+      const heads = questions.map((question) => question.header).filter(Boolean).join(", ");
+      return new Text(`${theme.fg("toolTitle", theme.bold("ask"))} ${theme.fg("accent", `${questions.length} question${questions.length === 1 ? "" : "s"}`)}${heads ? ` ${theme.fg("muted", heads)}` : ""}`, 0, 0);
+    },
+    renderResult(result, _options, theme) {
+      const details = result.details as AskResult | undefined;
+      if (!details) return new Container();
+      if (details.cancelled && details.answers.length === 0) return new Text(theme.fg("warning", "put away without answering"), 0, 0);
+      const lines = details.answers.map((answer) => `${theme.fg("success", "✓")} ${theme.fg("muted", answer.question.replace(/\s+/g, " ").slice(0, 60))} ${theme.fg("dim", "→")} ${theme.fg("accent", answer.kind === "multi" ? (answer.selected ?? []).join(", ") : answer.answer ?? "")}`);
+      return new Text(lines.join("\n"), 0, 0);
+    },
+  });
+}

package/src/ask/types.ts

@@ -0,0 +1,55 @@
+/**
+ * The questionnaire's shape: what a model (or the planning panel) asks, and
+ * what comes back. The same shape `ask_user_question` has had in pi, so a
+ * model's habits carry over: 1-4 questions, 2-4 options each, a short header,
+ * multi-select, and a per-option preview (Markdown: a mockup, a snippet, a
+ * diagram) shown beside the options.
+ */
+
+/** The questionnaire tool's name, in this session and in the agents that may ask. */
+export const ASK_TOOL = "ask_user_question";
+
+export const MAX_QUESTIONS = 4;
+export const MIN_OPTIONS = 2;
+export const MAX_OPTIONS = 4;
+export const MAX_HEADER = 16;
+export const MAX_LABEL = 60;
+
+/** The row under every question's options where the user writes their own answer. */
+export const OWN_ANSWER = "Type something.";
+
+/** Labels the questionnaire keeps for its own rows. */
+export const RESERVED = new Set(["other", OWN_ANSWER.toLowerCase(), "next"]);
+
+export interface AskOption {
+  label: string;
+  description?: string;
+  /** Markdown shown beside the options while this one is focused. */
+  preview?: string;
+  /** An image file (PNG, JPEG, GIF or WebP) shown with the preview: a screenshot, a rendered mockup. */
+  image?: string;
+}
+
+export interface AskQuestion {
+  question: string;
+  /** A short chip naming the question (a topic, or who asks it). */
+  header: string;
+  options: AskOption[];
+  multiSelect?: boolean;
+}
+
+export interface AskAnswer {
+  questionIndex: number;
+  question: string;
+  /** A picked option, the user's own words, or several picked options. */
+  kind: "option" | "custom" | "multi";
+  answer: string | null;
+  selected?: string[];
+  notes?: string;
+}
+
+export interface AskResult {
+  answers: AskAnswer[];
+  cancelled: boolean;
+  globalNote?: string;
+}

package/src/ask/view.ts

@@ -0,0 +1,159 @@
+/**
+ * The questionnaire drawn: a chip per question, the question in Markdown, its
+ * options (each with its description in Markdown), the row for your own
+ * answer, and — when options carry one — the focused option's preview in a
+ * box beside them (or under them in a narrow terminal). Pure: state in, lines
+ * out, exactly `width` columns and at most `height` rows.
+ */
+import { basename } from "node:path";
+import { textWidth } from "../width.ts";
+import { beside, bold, box, fill, fit, markdownLines, paint, wrap, type LobbyTheme } from "../lobby/layout.ts";
+import { imageLines, type ImagePreview } from "./image.ts";
+import { isAnswered, type AskState } from "./state.ts";
+import { OWN_ANSWER, type AskQuestion } from "./types.ts";
+
+/** Terminals at least this wide show the preview beside the options. */
+export const SIDE_BY_SIDE_MIN = 96;
+/** Rows the preview box keeps at least, and at most. */
+const PREVIEW_MIN = 6;
+const PREVIEW_MAX = 40;
+/** A preview box needs this many inner rows to draw an image in; smaller ones name the file. */
+const IMAGE_MIN_ROWS = 6;
+/** Option descriptions sit under their label, past the marker and number. */
+const DESCRIPTION_INDENT = 7;
+
+const RECOMMENDED = /\s*\(recommended\)\s*$/i;
+
+function chips(state: AskState, theme?: LobbyTheme): string {
+  if (state.questions.length === 1) return paint(theme, "muted", state.questions[0]!.header);
+  return state.questions
+    .map((question, index) => {
+      const label = ` ${index + 1} ${question.header}${isAnswered(state, index) ? " ✓" : ""} `;
+      if (index === state.tab) return bold(theme, paint(theme, "accent", `[${label.trim()}]`));
+      return paint(theme, isAnswered(state, index) ? "success" : "muted", label.trim());
+    })
+    .join(paint(theme, "dim", "  ·  "));
+}
+
+function optionLabel(label: string, focused: boolean, theme?: LobbyTheme): string {
+  const recommended = RECOMMENDED.test(label);
+  const plain = label.replace(RECOMMENDED, "");
+  const text = focused ? bold(theme, plain) : plain;
+  return recommended ? `${text} ${paint(theme, "success", "(Recommended)")}` : text;
+}
+
+/** The options and the own-answer row, each option with its description beneath. */
+function optionLines(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  const cursor = state.cursor[state.tab] ?? 0;
+  const picked = state.picked[state.tab] ?? [];
+  const lines: string[] = [];
+  question.options.forEach((option, index) => {
+    const focused = cursor === index && !state.editing;
+    const pointer = focused ? paint(theme, "accent", "›") : " ";
+    const mark = question.multiSelect ? (picked.includes(index) ? "☑" : "☐") : picked.includes(index) ? "●" : "○";
+    const lead = `${pointer} ${paint(theme, picked.includes(index) ? "accent" : "dim", mark)} ${paint(theme, "dim", `${index + 1}.`)} `;
+    const labelLines = wrap(optionLabel(option.label, focused, theme), Math.max(1, width - textWidth(lead)));
+    lines.push(`${lead}${labelLines[0] ?? ""}`, ...labelLines.slice(1).map((line) => `${" ".repeat(textWidth(lead))}${line}`));
+    if (option.description?.trim()) {
+      const indent = " ".repeat(DESCRIPTION_INDENT);
+      for (const line of markdownLines(option.description.trim(), Math.max(1, width - DESCRIPTION_INDENT), theme)) lines.push(line ? `${indent}${paint(theme, "muted", line)}` : "");
+    }
+  });
+  const ownFocused = cursor === question.options.length;
+  const pointer = ownFocused || state.editing ? paint(theme, "accent", "›") : " ";
+  const own = state.typed[state.tab];
+  const lead = `${pointer} ${paint(theme, own ? "accent" : "dim", "✎")}    `;
+  const room = Math.max(1, width - textWidth(lead));
+  if (state.editing) {
+    const draft = wrap(`${state.draft}▏`, room);
+    lines.push(`${lead}${paint(theme, "accent", draft[0] ?? "")}`, ...draft.slice(1).map((line) => `${" ".repeat(textWidth(lead))}${paint(theme, "accent", line)}`));
+  } else {
+    lines.push(`${lead}${own ? paint(theme, "accent", `“${own}”`) : paint(theme, ownFocused ? "text" : "dim", OWN_ANSWER)}`);
+  }
+  return lines;
+}
+
+interface Preview {
+  label: string;
+  text: string;
+  image?: string;
+}
+
+/** The preview to show: the focused option's, when any option in the question has one (Markdown or an image). */
+function previewOf(state: AskState, question: AskQuestion): Preview | undefined {
+  if (!question.options.some((option) => option.preview?.trim() || option.image?.trim())) return undefined;
+  const cursor = state.cursor[state.tab] ?? 0;
+  const option = question.options[cursor];
+  if (!option) return { label: OWN_ANSWER, text: "" };
+  return { label: option.label.replace(RECOMMENDED, ""), text: option.preview?.trim() ?? "", ...(option.image?.trim() ? { image: option.image.trim() } : {}) };
+}
+
+/** The image part of a preview: drawn when the box has room, else named. It never takes the box's last rows from the text entirely. */
+function imageBlock(preview: Preview, inner: number, innerRows: number, textRows: number, frame: AskFrame, theme?: LobbyTheme): string[] {
+  if (!preview.image) return [];
+  const loaded = frame.images?.get(preview.image);
+  const textRoom = textRows > 0 ? Math.min(textRows + 1, Math.max(2, Math.floor(innerRows / 3))) : 0;
+  const rows = innerRows - textRoom;
+  if (!loaded) return [paint(theme, "muted", `Image: ${preview.image}`)];
+  if (rows < IMAGE_MIN_ROWS) return [paint(theme, "muted", `Image: ${basename(preview.image)} (the terminal is too small to draw it)`)];
+  return imageLines(loaded, inner, rows, theme);
+}
+
+/** The preview in a box at most `rows` tall; an image keeps within `fits` rows, which the terminal surely shows. */
+function previewBox(preview: Preview, width: number, rows: number, theme: LobbyTheme | undefined, frame: AskFrame, fits = rows): string[] {
+  const inner = Math.max(1, width - 4);
+  const text = preview.text ? markdownLines(preview.text, inner, theme) : [];
+  const image = imageBlock(preview, inner, Math.min(rows, fits) - 2, text.length, frame, theme);
+  const joined = [...image, ...(image.length > 0 && text.length > 0 ? [""] : []), ...text];
+  const body = joined.length > 0 ? joined : [paint(theme, "dim", "No preview for this one.")];
+  const height = Math.max(3, Math.min(rows, body.length + 2));
+  const more = body.length > height - 2 ? `${body.length - (height - 2)} more lines` : "";
+  return box(width, height, body, { title: `Preview · ${preview.label}`, ...(more ? { right: more } : {}), theme });
+}
+
+function hints(state: AskState, question: AskQuestion, width: number, theme?: LobbyTheme): string[] {
+  const parts = state.editing
+    ? ["enter keep it", "esc back to the options"]
+    : [
+        "↑↓ move",
+        question.multiSelect ? "space pick · enter next" : "enter choose",
+        `1-${question.options.length} pick`,
+        ...(state.questions.length > 1 ? ["←→ questions"] : []),
+        "esc put away",
+      ];
+  return wrap(paint(theme, "dim", parts.join(" · ")), width);
+}
+
+/** Around the questions: who is asking (an agent the oracle relays for), and the option images, read beforehand. */
+export interface AskFrame {
+  from?: string;
+  images?: ReadonlyMap<string, ImagePreview>;
+}
+
+/** The whole questionnaire in a box, `width` wide and at most `height` rows. */
+export function renderAsk(state: AskState, width: number, height: number, theme?: LobbyTheme, frame: AskFrame = {}): string[] {
+  const question = state.questions[state.tab];
+  if (!question || width < 20 || height < 6) return [];
+  const inner = width - 4;
+  const head = [chips(state, theme), "", ...markdownLines(question.question, inner, theme), ""];
+  const foot = ["", ...hints(state, question, inner, theme)];
+  const preview = previewOf(state, question);
+  let body: string[];
+  if (preview && inner >= SIDE_BY_SIDE_MIN) {
+    const left = Math.floor(inner * 0.42);
+    const options = optionLines(state, question, left, theme);
+    const rows = Math.max(PREVIEW_MIN, Math.min(PREVIEW_MAX, height - 2 - head.length - foot.length));
+    const side = previewBox(preview, inner - left - 2, Math.max(rows, Math.min(options.length, PREVIEW_MAX)), theme, frame, rows);
+    body = beside([fill(options, Math.max(options.length, side.length), left), side], "  ");
+  } else {
+    const options = optionLines(state, question, inner, theme);
+    const room = height - 2 - head.length - foot.length - options.length - 1;
+    body = preview && room >= 3 ? [...options, "", ...previewBox(preview, inner, Math.min(PREVIEW_MAX, room), theme, frame)] : options;
+  }
+  const content = [...head, ...body, ...foot];
+  // Too tall for the terminal: the question and hints stay, the middle is cut.
+  const fitted = content.length > height - 2 ? [...content.slice(0, height - 2 - foot.length), ...foot] : content;
+  const count = state.questions.length > 1 ? `Question ${state.tab + 1} of ${state.questions.length}` : "Question";
+  const title = frame.from ? `${frame.from} asks · ${count}` : count;
+  return box(width, fitted.length + 2, fitted.map((line) => fit(line, inner)), { title, focused: true, theme });
+}

package/src/execution/agent-runner.ts

@@ -4,7 +4,11 @@ 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 { runPiAgent, spawnPiProcess, type PiStreamEvent, type ProcessRunner } from "./pi-runner.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 { ASK_ENV } from "../ask/relay.ts";
+import { ASK_TOOL } from "../ask/types.ts";
 
 export interface AgentContext {
   task: string;
@@ -58,8 +62,49 @@ export interface AgentRequest {
   /** The classifier routed this run down from this configured profile (receipts and metrics show it). */
   routedFrom?: string;
   route?: string;
+  /** Under a task time budget: the run's allotted time, which replaces `timeoutMs`. */
+  time?: AgentTime;
+  /** Lets the agent ask the user (ask_user_question, relayed through the master); its clocks wait for the answers. */
+  onAsk?: RelayAsk;
 }
 
+/**
+ * A run under a task time budget. The agent is told its minutes up front,
+ * warned at 75%, and asked to stop and report when they run out. A worker
+ * then reports where it left off and how much more it needs; `onTimeUp`
+ * (the engine asking the user) grants more, and the same agent carries on.
+ */
+export interface AgentTime {
+  /** When the delegation's time runs out (epoch ms); moved out when more is granted, shared by retries and re-runs. */
+  endsAt: number;
+  /** The allotment, as the agent and the lobby see it. */
+  allotMs: number;
+  /** What the agent is told about its time, in its context. */
+  note?: string;
+  /** Workers only: decide on more time once it has reported where it left off; resolve with ms, 0 to stop it. */
+  onTimeUp?: (run: AgentRun, report: string) => Promise<number>;
+}
+
+/** The warning at 75% of an allotment. */
+export function headsUpMessage(leftMs: number, allotMs: number): string {
+  return `bot-lobby: about ${formatMinutes(leftMs)} of your ${formatMinutes(allotMs)} for this step are left. Finish what you have started and make sure it works; leave nice-to-haves.`;
+}
+
+/** The steer when an allotment is spent: a worker says where it left off and what more it needs; any other role reports what it has. */
+export function timeUpMessage(allotMs: number, canAskForMore: boolean): string {
+  return canAskForMore
+    ? `bot-lobby: your ${formatMinutes(allotMs)} for this step are up. Stop here: finish or revert the edit in progress so every file is consistent, start nothing new, and write your report now in the required format, adding \`## Left Off\` (what you were doing and what is still to do) and \`## More Time\` (how many more minutes you need, and why). The user decides whether you get more time to finish.`
+    : `bot-lobby: your ${formatMinutes(allotMs)} are up. Stop now and write your report in the required format with what you have.`;
+}
+
+/** The follow-up that sends an agent on once the user gave it more time. */
+export function carryOnMessage(extraMs: number): string {
+  return `bot-lobby: the user gave you ${formatMinutes(extraMs)} more. Carry on from where you left off and finish the step, then write your final report in the required format (leave out Left Off and More Time if you finish).`;
+}
+
+/** Least time an attempt starts with; a retry with less than this left is not started. */
+const MIN_ATTEMPT_MS = 60_000;
+
 /** The watchdog fields of an AgentRequest, taken from the workflow config. */
 export function watchdogOptions(workflow: {
   maxAgentRetries: number;
@@ -91,13 +136,18 @@ function retryable(run: AgentRun): boolean {
 export async function runAgent(request: AgentRequest, run: ProcessRunner = spawnPiProcess): Promise<AgentRun> {
   const startedAt = new Date().toISOString();
   const attempts = Math.max(1, (request.retries ?? 0) + 1);
+  // 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;
   for (let attempt = 1; attempt <= attempts; attempt++) {
-    last = await runAgentOnce(request, run, attempt, startedAt);
+    last = await runAgentOnce(request, run, attempt, startedAt, edits);
     request.onAttemptEnd?.(last);
     if (!retryable(last)) break;
+    // Under a budget a retry only uses what is left of the allotment.
+    if (request.time && request.time.endsAt - Date.now() < MIN_ATTEMPT_MS) break;
   }
-  return last!;
+  const edited = edits.list();
+  return edited.length > 0 ? { ...last!, edited } : last!;
 }
 
 /** Abort every in-flight subagent (session shutdown, user cancel). */
@@ -120,31 +170,36 @@ function baseRun(request: AgentRequest, runId: string, startedAt: string, attemp
     ...(request.thinking ? { thinking: request.thinking } : {}),
     ...(request.routedFrom ? { routedFrom: request.routedFrom } : {}),
     ...(request.route ? { route: request.route } : {}),
+    ...(request.time ? { allotMs: request.time.allotMs, endsAt: request.time.endsAt } : {}),
     ...(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];
+  const extra = [...(request.extraTools ?? []), ...(request.onAsk ? [ASK_TOOL] : [])];
+  if (extra.length === 0) return tools;
+  return [...(tools ?? []), ...extra];
 }
 
 /**
  * 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): Promise<AgentRun> {
+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);
   request.onUpdate?.(base);
-  const live = createLiveRun(base, request);
+  const live = createLiveRun(base, request, edits);
 
   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 time = request.time;
+    const left = time ? Math.max(MIN_ATTEMPT_MS, time.endsAt - Date.now()) : 0;
+    const wrapUp = time ? 0 : request.wrapUpAt && request.wrapUpAt > 0 && request.wrapUpAt < 1 ? Math.floor(request.timeoutMs * request.wrapUpAt) : 0;
+    const onTimeUp = time?.onTimeUp;
     const result = await runPiAgent({
       cwd: request.cwd,
       task: request.instruction,
@@ -152,9 +207,29 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
       tools: toolsFor(request),
       model: request.model,
       thinking: request.thinking,
-      timeoutMs: request.timeoutMs,
+      timeoutMs: time ? left + REPORT_GRACE_MS : request.timeoutMs,
+      ...(time ? {
+        time: {
+          upAtMs: left,
+          headsUpAtMs: left >= 4 * 60_000 ? Math.floor(left * 0.75) : 0,
+          headsUpMessage: headsUpMessage(left - Math.floor(left * 0.75), time.allotMs),
+          upMessage: timeUpMessage(time.allotMs, Boolean(onTimeUp)),
+          graceMs: REPORT_GRACE_MS,
+          ...(onTimeUp ? {
+            onTimeUp: async (report: string) => {
+              const extraMs = await onTimeUp(live.current(), report);
+              if (extraMs > 0) {
+                time.endsAt = Date.now() + extraMs;
+                live.annotate({ note: `given ${formatMinutes(extraMs)} more`, noteKind: "info" });
+              }
+              return { extraMs, message: carryOnMessage(extraMs) };
+            },
+          } : {}),
+        },
+      } : {}),
       signal,
-      env: request.env,
+      ...(request.onAsk ? { onAsk: request.onAsk } : {}),
+      env: request.onAsk ? { ...request.env, [ASK_ENV]: "1" } : request.env,
       stallTimeoutMs: request.stallTimeoutMs,
       toolStallTimeoutMs: request.toolStallTimeoutMs,
       wrapUpAtMs: wrapUp,
@@ -174,6 +249,8 @@ async function runAgentOnce(request: AgentRequest, run: ProcessRunner, attempt:
       model: result.model ?? current.model,
       ...(result.stalled ? { stalled: true } : {}),
       ...(result.wrappedUp ? { wrappedUp: true } : {}),
+      ...(result.timeUp ? { timeUp: true } : {}),
+      ...(result.extendedMs ? { extendedMs: result.extendedMs } : {}),
       note: undefined,
       noteKind: undefined,
     };
@@ -198,7 +275,7 @@ const THROTTLE_MS = 2000;
  * `onUpdate`: activity changes, retries and notes immediately, counters and
  * heartbeats at most every couple of seconds.
  */
-function createLiveRun(base: AgentRun, request: AgentRequest) {
+function createLiveRun(base: AgentRun, request: AgentRequest, edits: EditLog) {
   let state: AgentRun = base;
   let lastEmit = 0;
   const emit = (patch: Partial<AgentRun>, force: boolean) => {
@@ -212,6 +289,7 @@ function createLiveRun(base: AgentRun, request: AgentRequest) {
   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);
@@ -240,6 +318,20 @@ function createLiveRun(base: AgentRun, request: AgentRequest) {
       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 };