@bermudi/pi-delegate 0.1.18 → 0.1.20

package/README.md

@@ -35,17 +35,16 @@ delegate({
 ```
 
 Parent extension/MCP tools are not copied, and project instructions are rebuilt
-for the task's `cwd`. Omit `agent` when you want an ad-hoc task using delegate's
-normal inline defaults instead.
+for the task's `cwd`. Omit `agent` when you want an inline task using delegate's
+normal defaults instead.
 
 The other built-ins are:
 
 - `scout` — read-only investigation with `read`, `grep`, `find`, and `ls`.
 - `coder` — implementation and verification with `read`, `write`, `edit`, and
   `bash` in the shared workspace.
-- `reviewer` — review with `read` and `bash`, using a disposable scratch copy by
-  default. Set `workspace: "shared"` when a reviewer needs a persistent
-  `sessionId`.
+- `reviewer` — review with `read` and `bash` in the shared workspace by default.
+  Set `workspace: "scratch"` when its project changes should be discarded.
 
 ### Shared-write safety
 
@@ -64,7 +63,7 @@ visible batch-level warning while it is active.
 A same-named Markdown file can override any built-in (first definition wins
 across `.pi/agents/`, `~/.pi/agent/agents/`, `~/.agents/`, `.claude/agents/`,
 `~/.claude/agents/`). A prompt-only override keeps the built-in's tools and
-workspace — `scout` stays read-only and `reviewer` stays scratch unless the
+workspace — `scout` stays read-only and `reviewer` stays shared unless the
 file explicitly sets `tools` or `workspace`. Fresh built-ins inherit the
 parent's exact model object and thinking level; an explicit `model`/`thinking`
 in the Markdown file replaces that inheritance. Task fields always win. For
@@ -106,7 +105,7 @@ host filesystem.
 
 ### Git-native isolated writers
 
-Use `workspace: "isolated"` for synchronous, one-shot coding tasks that should
+Use `workspace: "isolated"` for sync or async one-shot coding tasks that should
 run in parallel without sharing a working tree:
 
 ```ts
@@ -128,10 +127,12 @@ still matches the baseline.
 
 A clean reconciliation reports `applied_unverified`: textual merging does not
 prove the code builds or tests pass, so the result includes a suggested
-verification call. Isolated mode currently requires Git, rejects async and
-session reuse, disables whole-task retries, and rejects repositories with
-submodules. It is separation, not confinement: absolute-path writes can still
-reach the host.
+verification call. Async isolated tasks prepare after returning their ticket and
+settle only after reconciliation. Cancellation never applies unfinished work; a
+completed proposal cancelled before source application is retained as a private
+ref and full patch. Isolated mode requires Git, rejects session reuse, disables
+whole-task retries, and rejects repositories with submodules. It is separation,
+not confinement: absolute-path writes can still reach the host.
 
 ### Token accounting
 
@@ -150,7 +151,7 @@ Async tickets keep running after the parent's turn settles, and pi renders an
 idle session — so delegate adds three signals:
 
 - **Footer status** — while any ticket is active, the footer shows
-  `⏳ 2 subagents · t5042v19`, updated live as subagents start and finish.
+  `⏳ 2 subagents · t5042v19 · /subagents`, updated live as subagents start and finish.
 - **Settle warning** — the first time a turn settles with a ticket still
   active, a warning notification names the ticket and reminds you that
   quitting aborts it. Once per ticket; the footer carries it from there.
@@ -163,6 +164,54 @@ the mitigation there; on quit, delegate also prints a trace line to the
 terminal naming the aborted tickets and agents, and on `/reload` it shows a
 warning notification.
 
+### Live subagent browser
+
+Press **Ctrl+Shift+B** from the editor, or run **`/subagents`**, to open a live
+browser without sending a model request. It shows both sync tasks and async
+tickets, including retained completed work. Your draft is left untouched.
+
+| Key | Action |
+| --- | --- |
+| ↑ / ↓ | Select an agent |
+| Tab / ← / → | Switch between tool activity and assistant responses |
+| PgUp / PgDn | Scroll the selected view |
+| Home / End | Jump to oldest retained text / follow live output |
+| p | Pause or resume the selected agent's **whole async ticket** |
+| Esc | Close and return to your draft |
+
+The view shows running commands, tool results, edited file paths, queue
+dependencies, errors, token counts and activity age. Pause controls use the
+same cooperative boundary described below; they do not freeze subprocesses.
+Down in the editor keeps its normal behavior rather than intercepting menus
+or replacing a custom editor.
+
+This is a bounded live preview, not a transcript archive: assistant text keeps
+the current attempt's last 32K characters (no thinking blocks); tool activity
+shows up to 100 recent calls with output tails. The browser retains the last
+20 completed sync calls. Async results remain available until the existing
+ticket cleanup removes them (eligible after 30 minutes). Nothing is recovered
+from transcripts after a restart. A refresh timer runs only while the browser
+is open and is cleared on close or shutdown. This feature requires Pi's TUI,
+not print/JSON/RPC mode.
+
+### Pause and resume
+
+Pause an async ticket with `delegate({ ticketAction: "pause", ticket: "<id>" })`;
+continue it with `ticketAction: "resume"`. Both return immediately.
+
+Each current model response and its tool calls finish, then the agent waits
+before its next model request. Queued tasks do not start. **Pausing** means
+work is reaching that boundary; **paused** means it has reached it. A task
+that finishes naturally may complete instead. Resume keeps the same live
+conversations, including scratch workspaces.
+
+Pause is not cancellation, rollback, or a process freeze. Background commands
+can keep running, and files may be unfinished. In-progress isolated preparation
+or application finishes before pausing. Sessions, concurrency slots and
+workspace reservations remain held. Inactivity checks stop while parked, but
+explicit wall-clock deadlines keep counting. Wait does not resume work; cancel
+still works. Pauses do not survive Pi exit or reload.
+
 ### Stall detection and cancellation
 
 `stallTimeoutMs` is an inactivity watchdog, not a hard execution deadline. When
@@ -216,8 +265,8 @@ over an installed extension.
   and workspace, and an explicit `model`/`thinking` replaces parent inheritance.
   For `default`, the `delegate.json` override maps are ignored (task fields still
   win); for the other built-ins, those maps win field-by-field over frontmatter.
-- **Ad-hoc subagent** — A subagent created from inline task fields instead of a
-  named Markdown agent profile. In current output this is labeled `ad-hoc`.
+- **Inline subagent** — A subagent created from inline task fields instead of a
+  named Markdown agent profile. In current output this is labeled `inline`.
 - **Inline task** — The task object itself when its configuration is supplied
   directly in the delegate call. Prefer this term over “inline agent” when
   talking about the API shape.
@@ -230,7 +279,7 @@ over an installed extension.
 - **Resumed subagent** — A subagent rehydrated from a previous session `.jsonl`
   via `resumeFrom`. It can also be pooled by providing a `sessionId`.
 - **Async ticket** — A background execution handle returned when top-level
-  `async: true` is used. Poll, wait, or cancel tickets with top-level
+  `async: true` is used. Poll, wait, pause, resume, or cancel tickets with top-level
   `ticketAction: "poll"`, `ticketAction: "wait"` (blocks until the ticket settles;
   optional `timeoutMs`), or `ticketAction: "cancel"`.
 - **Skill** — A `SKILL.md` instruction bundle injected into the subagent system

package/agents.ts

@@ -120,7 +120,7 @@ export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
   [DEFAULT_AGENT_NAME]: {
     name: DEFAULT_AGENT_NAME,
     description:
-      "General-purpose subagent mirroring the live parent model, thinking level, native tools, and base prompt. Prefer it for general work; pick a specialist only when its role, tool limits, or scratch workspace genuinely fit.",
+      "General-purpose subagent mirroring the live parent model, thinking level, native tools, and base prompt. Prefer it for general work; pick a specialist when its role fits.",
     tools: DEFAULT_TOOLS,
     systemPrompt: "",
     builtin: true,

package/assistant-preview.ts

@@ -0,0 +1,31 @@
+/** Human-facing, bounded text preview. Never includes thinking blocks or reads
+ * transcripts from disk. Updates replace the current response, not append
+ * streaming snapshots; completed responses remain available for scrollback. */
+export class AssistantPreview {
+  private completed = "";
+  private current = "";
+  static readonly limit = 32_768;
+
+  update(text: string): void {
+    // Empty synthetic provider failures must not erase a streamed response.
+    if (text) this.current = text.slice(-AssistantPreview.limit);
+  }
+
+  finish(text: string): void {
+    this.update(text);
+    if (this.current) {
+      this.completed = [this.completed, this.current]
+        .filter(Boolean)
+        .join("\n\n")
+        .slice(-AssistantPreview.limit);
+      this.current = "";
+    }
+  }
+
+  get text(): string {
+    return [this.completed, this.current]
+      .filter(Boolean)
+      .join("\n\n")
+      .slice(-AssistantPreview.limit);
+  }
+}

package/browser-state.ts

@@ -0,0 +1,250 @@
+import type { DelegateRuntime } from "./runtime.ts";
+import type {
+  AsyncTicket,
+  DelegateDetails,
+  TaskProgress,
+  ToolActivity,
+} from "./types.ts";
+
+interface SyncDetails {
+  tasks: { prompt?: string }[];
+  progress: TaskProgress[];
+  results: { output?: string; error?: string }[];
+  serializedNotice?: string;
+  dispatchWarning?: string;
+}
+
+/** Finished sync calls must not pin entire tool arguments/results after the
+ * parent compacts. Keep only primitive display arguments and bounded text. */
+function compactProgress(p: TaskProgress): TaskProgress {
+  let budget = 65_536;
+  const activities: ToolActivity[] = [];
+  const take = (text: string): string => {
+    const limit = Math.min(4096, budget);
+    if (limit <= 0) return "";
+    const value = text.length > limit ? `…${text.slice(-limit)}` : text;
+    budget -= value.length;
+    return value;
+  };
+  for (const tool of p.activities.slice(-100).reverse()) {
+    if (budget <= 0) break;
+    const args: Record<string, unknown> = {};
+    for (const key of [
+      "path",
+      "file_path",
+      "command",
+      "pattern",
+      "query",
+      "url",
+      "task",
+      "prompt",
+      "offset",
+      "limit",
+    ]) {
+      const value = tool.args[key];
+      if (typeof value === "string" && budget > 0) args[key] = take(value);
+      else if (typeof value === "number") args[key] = value;
+    }
+    const output = tool.result
+      ? tool.result.content
+          .filter((part) => part.type === "text")
+          .slice(-20)
+          .map((part) => part.text?.slice(-4096) ?? "")
+          .join("\n")
+      : (tool.liveOutput ?? "");
+    const text = budget > 0 ? take(output) : "";
+    activities.push({
+      id: tool.id,
+      name: tool.name,
+      args,
+      startTime: tool.startTime,
+      endTime: tool.endTime,
+      result: tool.result
+        ? { isError: tool.result.isError, content: [{ type: "text", text }] }
+        : undefined,
+      liveOutput: tool.result ? undefined : text,
+    });
+  }
+  return {
+    ...p,
+    assistantPreview: p.assistantPreview?.slice(-32_768),
+    error: p.error?.slice(0, 4096),
+    activities: activities.reverse(),
+    warnings: [
+      ...(p.warnings ?? []).slice(0, 10).map((s) => s.slice(0, 4096)),
+      ...(activities.length < p.activities.length
+        ? ["Earlier tool activity omitted from retained sync preview."]
+        : []),
+    ],
+  };
+}
+
+function compactDetails(details: SyncDetails): SyncDetails {
+  return {
+    tasks: details.tasks.map((task) => ({
+      prompt: task.prompt?.slice(0, 4096),
+    })),
+    progress: details.progress.map(compactProgress),
+    results: details.results.map((result) => ({
+      output: result.output?.slice(-32_768),
+      error: result.error?.slice(0, 4096),
+    })),
+    serializedNotice: details.serializedNotice?.slice(0, 4096),
+    dispatchWarning: details.dispatchWarning?.slice(0, 4096),
+  };
+}
+
+interface SyncRun {
+  details: SyncDetails;
+  finished: boolean;
+  created: number;
+  error?: string;
+}
+
+/** UI-only history. Active sync runs are never evicted; retain the last twenty
+ * finished calls. Async history stays owned by the existing ticket registry. */
+export class BrowserHistory {
+  readonly runs = new Map<string, SyncRun>();
+  generation = 0;
+
+  reset(): void {
+    this.generation++;
+    this.runs.clear();
+  }
+
+  update(
+    id: string,
+    details: DelegateDetails | undefined,
+    finished: boolean,
+    generation = this.generation,
+  ): void {
+    if (generation !== this.generation) return;
+    if (!details?.progress.length) {
+      if (finished)
+        this.fail(
+          id,
+          "Dispatch ended before tasks could start; see the delegate result.",
+        );
+      return;
+    }
+    const created = this.runs.get(id)?.created ?? Date.now();
+    this.runs.delete(id);
+    this.runs.set(id, {
+      details: finished ? compactDetails(details) : details,
+      finished,
+      created,
+    });
+    this.prune();
+  }
+
+  fail(id: string, error: unknown, generation = this.generation): void {
+    if (generation !== this.generation) return;
+    const run = this.runs.get(id);
+    if (!run) return;
+    run.finished = true;
+    run.details = compactDetails(run.details);
+    run.error = (error instanceof Error ? error.message : String(error)).slice(
+      0,
+      4096,
+    );
+    this.runs.delete(id);
+    this.runs.set(id, run);
+    this.prune();
+  }
+
+  private prune(): void {
+    const finished = [...this.runs].filter(([, run]) => run.finished);
+    for (const [id] of finished.slice(0, -20)) this.runs.delete(id);
+  }
+}
+
+export interface BrowserRow {
+  key: string;
+  batch: string;
+  created: number;
+  progress: TaskProgress;
+  siblings: TaskProgress[];
+  prompt: string;
+  output?: string;
+  error?: string;
+  ticket?: AsyncTicket;
+  finished: boolean;
+  notice?: string;
+}
+
+export function browserRows(
+  runtime: DelegateRuntime,
+  history: BrowserHistory,
+): BrowserRow[] {
+  const rows: BrowserRow[] = [];
+  for (const ticket of runtime.tickets.values()) {
+    for (const progress of ticket.progress) {
+      const result = ticket.results[progress.index];
+      rows.push({
+        key: `${ticket.id}:${progress.index}`,
+        batch: ticket.id,
+        created: ticket.created,
+        progress,
+        siblings: ticket.progress,
+        prompt: ticket.tasks[progress.index]?.prompt ?? progress.task,
+        output: result?.output,
+        error: result?.error ?? ticket.error,
+        ticket,
+        finished: ticket.status !== "running" && ticket.status !== "cancelling",
+        notice: [ticket.serializedNotice, ticket.dispatchWarning]
+          .filter(Boolean)
+          .join("\n"),
+      });
+    }
+  }
+  for (const [id, run] of history.runs) {
+    for (const progress of run.details.progress) {
+      const result = run.details.results[progress.index];
+      rows.push({
+        key: `sync:${id}:${progress.index}`,
+        batch: `sync ${id.slice(-8)}`,
+        created: run.created,
+        progress,
+        siblings: run.details.progress,
+        prompt: run.details.tasks[progress.index]?.prompt ?? progress.task,
+        output: result?.output,
+        error: result?.error ?? run.error,
+        finished: run.finished,
+        notice: [run.details.serializedNotice, run.details.dispatchWarning]
+          .filter(Boolean)
+          .join("\n"),
+      });
+    }
+  }
+  return rows.sort(
+    (a, b) =>
+      Number(a.finished) - Number(b.finished) ||
+      b.created - a.created ||
+      a.batch.localeCompare(b.batch) ||
+      a.progress.index - b.progress.index,
+  );
+}
+
+export function browserRowStatus(row: BrowserRow): string {
+  const p = row.progress;
+  if (p.incomplete) return "incomplete — worker may still be active";
+  if (p.status === "done") return "done";
+  if (p.status === "failed") return "failed";
+  if (row.ticket?.status === "cancelling") return "cancelling";
+  if (row.finished)
+    return row.error ? "failed" : (row.ticket?.status ?? "finished");
+  if (p.paused) return "paused";
+  if (p.status === "pending") {
+    if (row.ticket?.pause && row.ticket.pause.state !== "running")
+      return "queued — ticket paused";
+    const before =
+      p.waitingFor === undefined ? undefined : row.siblings[p.waitingFor];
+    if (before && before.status !== "done" && before.status !== "failed")
+      return `queued — waiting for ${before.id ?? `task ${before.index + 1}`}`;
+    return "queued — waiting for preparation or capacity";
+  }
+  const phase = p.activity ?? "starting";
+  return row.ticket?.pause?.state === "pausing"
+    ? `${phase} — pausing after turn`
+    : phase;
+}