@pi-unipi/fusion 2.19.2 → 2.20.0

package/README.md

@@ -92,14 +92,19 @@ persist across handoffs. The sidekick's context compacts independently of the
 lead's (it is its own pi session). `sidekick({message, block:true})` waits by
 default; `block:false` returns immediately and delivers a
 `<subagent_completion_notification>`. Calling it while busy steers the same
-handoff. Background tasks keep that handoff open through their completion
+handoff. A handoff whose lead turn has ended — started with `block:false`,
+abandoned by a user message, or timed out — still wakes the lead with that same
+completion notification when its report lands, exactly once. Background tasks
+keep that handoff open through their completion
 notification and any follow-up turn, so the report is not released at an
 intermediate checkpoint. If a prompt arrives while the child is processing,
 Fusion retries it once with pi's `followUp` streaming behavior. Sidekick work
 renders as ordinary tool activity — handoff ids, `agent_id`, and
-`read_subagent` protocol text never reach the terminal. Detached
-handoffs stay visible in a live sidekick widget above the editor until their
-completion card arrives.
+`read_subagent` protocol text never reach the terminal. Sidekick output keeps
+that same format on the main surface, marked as sidekick-origin by a `▍` rail.
+While the sidekick works and the lead's turn is over, an animated
+`sidekick working` line above the editor shows the live tool count and elapsed
+time until the report lands.
 `read_subagent({agent_id?, block?, timeout?})` reads or waits for a handoff.
 
 The child receives `UNIPI_FUSION_CHILD=1` and `UNIPI_SUBAGENT_CHILD=1`; the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/fusion",
-  "version": "2.19.2",
+  "version": "2.20.0",
   "description": "Devin-style model picker, fusion presets (lead + sidekick), and Local Fusion runtime for UniPi",
   "type": "module",
   "main": "src/index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.19.2",
-    "@pi-unipi/subagents": "2.19.2"
+    "@pi-unipi/core": "2.20.0",
+    "@pi-unipi/subagents": "2.20.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/src/index.ts

@@ -16,7 +16,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AutocompleteProvider, AutocompleteSuggestions } from "@earendil-works/pi-tui";
-import { setSharedFusionStatus, UNIPI_PREFIX } from "@pi-unipi/core";
+import { createSpinnerLine, setSharedFusionStatus, UNIPI_PREFIX } from "@pi-unipi/core";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -40,8 +40,7 @@ import { estimateSavings } from "./savings.js";
 import { EDIT_NUDGE, bashNudge, leadPolicy, sidekickSystemPrompt, type FusionIdentity } from "./prompts.js";
 import { isTrivialShell, BASH_NUDGE_EVERY } from "./nudge.js";
 import { registerFusionTools } from "./tools.js";
-import { shouldShowSidekickWidget } from "./sidekick-widget.js";
-import { frameSidekick, markdownText, renderSidekickTranscript, sidekickWorkingHeader, type ThemeLike } from "./transcript.js";
+import { duration } from "./transcript.js";
 
 export const MODEL_COMMAND = `${UNIPI_PREFIX}model`;
 export const PRESET_COMMAND = `${UNIPI_PREFIX}fusion-preset`;
@@ -50,6 +49,73 @@ export function sidekickSessionPath(leadSessionId?: string): string {
   return join(homedir(), ".unipi", "state", "fusion", "sidekick", `${leadSessionId ?? "default"}.jsonl`);
 }
 
+export const SIDEKICK_WAKE_WIDGET_KEY = "fusion-sidekick-wake";
+
+/**
+ * The lead is idle when pi says so. Any failure (including a context without
+ * `isIdle`) counts as idle — same contract as the background-tasks wake line.
+ */
+export function isLeadIdle(ctx: { isIdle(): boolean }): boolean {
+  try {
+    return ctx.isIdle();
+  } catch {
+    return true;
+  }
+}
+
+/** Body of the live line. `undefined` collapses it without disposing the widget. */
+export function sidekickWakeText(progress: { toolCalls: number; startedAt: number } | undefined): string | undefined {
+  if (!progress) return undefined;
+  return `sidekick working · ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)} — resumes automatically when done`;
+}
+
+export interface SidekickWakeLine {
+  publish(ctx: ExtensionContext | undefined): void;
+  clear(ctx: ExtensionContext | undefined): void;
+}
+
+/**
+ * Self-animating "sidekick still working" line, shown while the sidekick is
+ * busy but the lead's turn has already ended (pi stopped its own loader).
+ *
+ * The widget owns an 80 ms frame timer, so it is installed ONCE while the
+ * condition holds and removed when it stops — never re-installed per progress
+ * tick.
+ */
+export function createSidekickWakeLine(deps: {
+  isBusy: () => boolean;
+  progress: () => { toolCalls: number; startedAt: number } | undefined;
+}): SidekickWakeLine {
+  let installed = false;
+
+  const removable = (ctx: ExtensionContext | undefined): ctx is ExtensionContext =>
+    Boolean(ctx?.hasUI) && typeof ctx?.ui.setWidget === "function";
+
+  return {
+    publish(ctx) {
+      if (!removable(ctx)) return;
+      const want = deps.isBusy() && isLeadIdle(ctx);
+      if (want && !installed) {
+        ctx.ui.setWidget(
+          SIDEKICK_WAKE_WIDGET_KEY,
+          createSpinnerLine({ text: () => sidekickWakeText(deps.progress()) }),
+          { placement: "aboveEditor" },
+        );
+        installed = true;
+      } else if (!want && installed) {
+        ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, undefined);
+        installed = false;
+      }
+    },
+    clear(ctx) {
+      if (!installed) return;
+      installed = false;
+      if (!removable(ctx)) return;
+      ctx.ui.setWidget(SIDEKICK_WAKE_WIDGET_KEY, undefined);
+    },
+  };
+}
+
 type Registry = { getAvailable(): Model<Api>[]; find(provider: string, id: string): Model<Api> | undefined };
 
 function registryOf(ctx: ExtensionContext): Registry | undefined {
@@ -120,10 +186,11 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   let leadToolCalls = 0;
   let editNudgedThisTurn = false;
   let bashStreak = 0;
-  let attached = false;
-  let widgetTimer: NodeJS.Timeout | undefined;
-  let widgetTimerKind: "publish" | "clear" | undefined;
-  let widgetLastAt = 0;
+
+  const wakeLine = createSidekickWakeLine({
+    isBusy: () => runtime?.isBusy() === true,
+    progress: () => runtime?.progress(),
+  });
 
   function identity(ctx: ExtensionContext): FusionIdentity {
     const reg = registryOf(ctx);
@@ -167,78 +234,11 @@ export default function fusionExtension(pi: ExtensionAPI): void {
     }
   }
 
-  function clearSidekickWidget(): void {
-    if (widgetTimer !== undefined) {
-      clearTimeout(widgetTimer);
-      widgetTimer = undefined;
-      widgetTimerKind = undefined;
-    }
-    const ctx = lastCtx;
-    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
-    const clear = () => {
-      widgetTimer = undefined;
-      widgetTimerKind = undefined;
-      widgetLastAt = Date.now();
-      ctx.ui.setWidget("fusion-sidekick", undefined);
-    };
-    const wait = Math.max(0, 150 - (Date.now() - widgetLastAt));
-    if (wait === 0) clear();
-    else {
-      widgetTimerKind = "clear";
-      widgetTimer = setTimeout(clear, wait);
-      widgetTimer.unref();
-    }
-  }
-
-  function publishSidekickWidget(): void {
-    const ctx = lastCtx;
-    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
-    const progress = runtime?.progress();
-    if (!runtime || !shouldShowSidekickWidget(runtime.isBusy(), attached) || !progress) {
-      ctx.ui.setWidget("fusion-sidekick", undefined);
-      return;
-    }
-    ctx.ui.setWidget("fusion-sidekick", (_tui, theme) => {
-      const themeLike = theme as unknown as ThemeLike & { bg: (color: string, text: string) => string };
-      return frameSidekick(themeLike, "working", renderSidekickTranscript(themeLike, {
-        events: progress.events,
-        droppedEvents: progress.droppedEvents,
-        header: sidekickWorkingHeader(themeLike, progress),
-        expanded: false,
-        isPartial: true,
-        renderText: markdownText,
-      }));
-    }, { placement: "aboveEditor" });
-  }
-
-  function publishSidekickWidgetLater(): void {
-    const ctx = lastCtx;
-    if (!ctx?.hasUI || typeof ctx.ui.setWidget !== "function") return;
-    if (widgetTimer !== undefined && widgetTimerKind === "publish") return;
-    if (widgetTimer !== undefined) {
-      clearTimeout(widgetTimer);
-      widgetTimer = undefined;
-      widgetTimerKind = undefined;
-    }
-    const wait = Math.max(0, 150 - (Date.now() - widgetLastAt));
-    const publish = () => {
-      widgetTimer = undefined;
-      widgetTimerKind = undefined;
-      widgetLastAt = Date.now();
-      publishSidekickWidget();
-    };
-    if (wait === 0) publish();
-    else {
-      widgetTimerKind = "publish";
-      widgetTimer = setTimeout(publish, wait);
-      widgetTimer.unref();
-    }
-  }
-
-  function publishStatusLater(): void {
-    if (lastCtx) {
-      publishStatus(lastCtx);
-      publishSidekickWidgetLater();
+  function publishStatusLater(ctx?: ExtensionContext): void {
+    const target = ctx ?? lastCtx;
+    if (target) {
+      publishStatus(target);
+      wakeLine.publish(target);
     }
   }
 
@@ -263,8 +263,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   }
 
   function stopRuntime(): void {
-    clearSidekickWidget();
-    attached = false;
+    wakeLine.clear(lastCtx);
     runtime?.kill();
     runtime = undefined;
     leadToolCalls = 0;
@@ -285,20 +284,10 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   registerFusionTools(pi, {
     getRuntime,
-    onReport: (ctx) => {
-      attached = false;
-      clearSidekickWidget();
-      publishStatus(ctx);
-    },
+    onReport: (ctx) => publishStatusLater(ctx),
     onHandoffStart: (ctx) => publishStatus(ctx),
-    onAttach: () => {
-      attached = true;
-      clearSidekickWidget();
-    },
-    onDetach: () => {
-      attached = false;
-      publishSidekickWidgetLater();
-    },
+    onAttach: (ctx) => publishStatusLater(ctx),
+    onDetach: (ctx) => publishStatusLater(ctx),
   });
   pi.registerCommand("unipi:fusion-stats", {
     description: "Estimated Fusion savings (sidekick tokens priced at lead rates)",
@@ -308,6 +297,10 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   pi.on("turn_start", () => {
     editNudgedThisTurn = false;
   });
+  // The wake line's condition flips when the LEAD goes idle, not when the
+  // sidekick reports progress, so re-evaluate on both turn end and settle.
+  pi.on("turn_end", (_event, ctx) => publishStatusLater(ctx));
+  pi.on("agent_settled", (_event, ctx) => publishStatusLater(ctx));
   pi.on("tool_result", (event) => {
     if (active?.kind !== "fusion") return;
     const toolName: string = event.toolName;

package/src/tools.ts

@@ -2,7 +2,7 @@ import { Text, type Component } from "@earendil-works/pi-tui";
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { SidekickRuntime, HandoffProgress, HandoffReport } from "./sidekick-runtime.js";
-import { duration, markdownText, renderSidekickTranscript, sidekickWorkingHeader } from "./transcript.js";
+import { duration, frameSidekick, markdownText, renderSidekickTranscript, sidekickWorkingHeader } from "./transcript.js";
 
 const SidekickParams = Type.Object({
   message: Type.String({ description: "A concrete implementation or verification brief for the sidekick" }),
@@ -22,6 +22,46 @@ export interface FusionToolDeps {
   onDetach?: (ctx: ExtensionContext) => void;
 }
 
+/**
+ * Exactly-once completion delivery for handoffs nobody is waiting on.
+ *
+ * `attach`/`detach` bracket every waiting period. The completion is sent only
+ * if the report lands (or has already landed) while no waiter is attached, and
+ * only once per handoff id.
+ */
+export function createCompletionDelivery(send: (report: HandoffReport) => void): {
+  attach(id: string): void;
+  detach(id: string, done: Promise<HandoffReport>): void;
+  consume(id: string): void;
+} {
+  const waiting = new Set<string>();
+  const armed = new Set<string>();
+  const delivered = new Set<string>();
+
+  return {
+    attach(id) {
+      waiting.add(id);
+    },
+    detach(id, done) {
+      waiting.delete(id);
+      // One continuation per handoff, however many times a waiter gives up.
+      if (armed.has(id)) return;
+      armed.add(id);
+      void done
+        .then((report) => {
+          if (waiting.has(id) || delivered.has(id)) return;
+          delivered.add(id);
+          send(report);
+        })
+        .catch(() => undefined);
+    },
+    consume(id) {
+      waiting.delete(id);
+      delivered.add(id);
+    },
+  };
+}
+
 function firstLine(value: string): string {
   return value.split("\n", 1)[0] ?? "";
 }
@@ -101,6 +141,21 @@ type ThemeLike = {
   bold: (text: string) => string;
 };
 
+type FramedTheme = ThemeLike & { bg: (color: string, text: string) => string };
+
+function transcriptStatus(partial: boolean, report: HandoffReport | undefined): "working" | "completed" | "error" {
+  if (partial) return "working";
+  return report?.status === "completed" ? "completed" : "error";
+}
+
+/**
+ * Sidekick output on the main surface: the same markdown/tool format the lead
+ * uses, marked as sidekick-origin by the existing `▍` rail.
+ */
+function frameTranscript(theme: ThemeLike, status: "working" | "completed" | "error", content: Component): Component {
+  return frameSidekick(theme as FramedTheme, status, content);
+}
+
 // Model-facing result text carries handoff ids and protocol instructions the
 // lead needs; none of it may reach the terminal. Anything rendered as plain
 // content goes through this first.
@@ -147,7 +202,7 @@ function renderToolTranscript(result: { content?: unknown; details?: unknown; is
   const partial = progress !== undefined;
   if (!events) return new Text(displayText(contentText(result.content)), 0, 0);
   const header = partial ? sidekickWorkingHeader(theme, progress, label) : reportHeader(theme, label, report);
-  return renderSidekickTranscript(theme, {
+  return frameTranscript(theme, transcriptStatus(partial, report), renderSidekickTranscript(theme, {
     events,
     droppedEvents: progress?.droppedEvents,
     header,
@@ -155,30 +210,34 @@ function renderToolTranscript(result: { content?: unknown; details?: unknown; is
     isPartial: partial,
     report,
     renderText: markdownText,
-  });
+  }));
 }
 
 function renderCompletionCard(theme: ThemeLike, report: HandoffReport | undefined): Component {
   if (!report) return new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0);
-  return renderSidekickTranscript(theme, {
+  return frameTranscript(theme, transcriptStatus(false, report), renderSidekickTranscript(theme, {
     events: report.events ?? [],
     header: reportHeader(theme, "sidekick", report),
     expanded: false,
     isPartial: false,
     report,
     renderText: markdownText,
-  });
+  }));
 }
 
 export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): void {
   pi.registerMessageRenderer("sidekick-completion", (message: { details?: HandoffReport }, _options, theme) => renderCompletionCard(theme as unknown as ThemeLike, message.details));
 
+  // One delivery mechanism for every handoff nobody is waiting on.
+  const completion = createCompletionDelivery((report) => {
+    pi.sendMessage(completionMessage(report) as never, { deliverAs: "followUp", triggerTurn: true } as never);
+  });
+
   pi.registerTool({
     name: "sidekick",
     label: "Sidekick",
     description: "Hand off work to your persistent sidekick subagent (one per session; context and shells persist across handoffs; runs on the same machine). block:true (default) waits and returns the report. block:false returns immediately and the report arrives later as a <subagent_completion_notification>. Calling again while a handoff is running injects the message as an interrupt rather than starting a second sidekick.",
     parameters: SidekickParams,
-    renderShell: "self",
     renderCall: (args, theme) => new Text(`${theme.fg("toolTitle", theme.bold("◆ sidekick"))} ${theme.fg("dim", firstLine(String(args.message)).slice(0, 100))}`, 0, 0),
     renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "sidekick"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -188,19 +247,20 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
       const handoff = runtime.handoff(params.message);
       if (!wasBusy) deps.onHandoffStart?.(ctx);
       if (params.block === false) {
-        void handoff.done.then((report) => {
-          deps.onReport?.(ctx, report);
-          pi.sendMessage(completionMessage(report) as never, { deliverAs: "followUp", triggerTurn: true } as never);
-        }).catch(() => undefined);
+        void handoff.done.then((report) => deps.onReport?.(ctx, report)).catch(() => undefined);
+        completion.detach(handoff.id, handoff.done);
         deps.onDetach?.(ctx);
         return result(`Handoff ${handoff.id} started in the background. You will receive a <subagent_completion_notification agent_id="${handoff.id}"> when it finishes; use read_subagent to wait.`, { background: true, id: handoff.id });
       }
       deps.onAttach?.(ctx);
+      completion.attach(handoff.id);
       const waited = await waitForReport(runtime, handoff.id, handoff.done, signal, ctx, onUpdate ? (update) => onUpdate(update as never) : undefined);
       if (waited.report) {
+        completion.consume(handoff.id);
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      completion.detach(handoff.id, handoff.done);
       deps.onDetach?.(ctx);
       if (waited.error) return result(`Handoff ${handoff.id} failed: ${waited.error}`, undefined, true);
       if (waited.aborted) return result(`${progressText(runtime, handoff.id)}\nHandoff ${handoff.id} aborted.`, undefined, true);
@@ -214,7 +274,6 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     label: "Read Sidekick",
     description: "Read a sidekick handoff report by agent_id (omit for the latest). block:true waits for completion (default timeout 2700s when omitted); block:false returns the current progress snapshot immediately.",
     parameters: ReadSubagentParams,
-    renderShell: "self",
     renderCall: (args, theme) => new Text(`${theme.fg("toolTitle", theme.bold("◆ read_subagent"))} ${theme.fg("dim", args.block === false ? "· snapshot" : "· waiting")}`, 0, 0),
     renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "read_subagent"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -224,16 +283,22 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
       if (!latest) return result("No sidekick handoff has run yet.", undefined, true);
       const id = params.agent_id ?? latest.id;
       const selected = runtime.reports.get(id);
-      if (selected) return result(reportText(selected), selected, selected.status !== "completed");
+      if (selected) {
+        completion.consume(id);
+        return result(reportText(selected), selected, selected.status !== "completed");
+      }
       if (id !== latest.id) return result(`No sidekick handoff found for ${id}.`, undefined, true);
       if (params.block !== true) return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`, { progress: runtime.progress(id), id });
       deps.onAttach?.(ctx);
+      completion.attach(id);
       const timeoutMs = (params.timeout ?? 2700) * 1000;
       const waited = await waitForReport(runtime, id, latest.done, signal, ctx, onUpdate ? (update) => onUpdate(update as never) : undefined, timeoutMs);
       if (waited.report) {
+        completion.consume(id);
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      completion.detach(id, latest.done);
       deps.onDetach?.(ctx);
       if (waited.error) return result(`Handoff ${id} failed: ${waited.error}`, undefined, true);
       if (waited.aborted) return result(`Handoff ${id} aborted.`, undefined, true);

package/src/transcript.ts

@@ -53,6 +53,13 @@ export interface TranscriptOptions {
   renderText: (markdown: string) => Component;
 }
 
+/**
+ * Non-expanded transcripts show this many most recent events. Windowing is the
+ * only cap: a completed handoff renders its events, it is never collapsed into
+ * a "N steps" stub.
+ */
+export const TRANSCRIPT_WINDOW = 8;
+
 function firstLine(value: string): string {
   return value.split("\n", 1)[0] ?? "";
 }
@@ -91,14 +98,8 @@ export function renderSidekickTranscript(theme: ThemeLike, opts: TranscriptOptio
   const box = new Container();
   box.addChild(new Text(opts.header, 0, 0));
 
-  if (!opts.isPartial && !opts.expanded) {
-    if (opts.report?.text) box.addChild(opts.renderText(opts.report.text));
-    box.addChild(new Text(theme.fg("dim", `${String(opts.events.length)} steps · expand to see the transcript`), 0, 0));
-    return box;
-  }
-
   const dropped = opts.droppedEvents ?? 0;
-  const start = opts.expanded ? 0 : Math.max(0, opts.events.length - 8);
+  const start = opts.expanded ? 0 : Math.max(0, opts.events.length - TRANSCRIPT_WINDOW);
   if (opts.expanded && dropped > 0) {
     box.addChild(new Text(theme.fg("dim", `… ${String(dropped)} earliest steps dropped`), 0, 0));
   } else if (start > 0) {
@@ -110,12 +111,13 @@ export function renderSidekickTranscript(theme: ThemeLike, opts: TranscriptOptio
     else if (event.text.trim()) box.addChild(opts.renderText(event.text.trim()));
   }
 
-  if (!opts.isPartial && opts.expanded && opts.report?.text) {
+  if (!opts.isPartial && opts.report?.text) {
     // The final assistant message usually IS the report; don't print it twice.
     const last = opts.events.at(-1);
-    if (last?.kind === "text" && last.text.trim() === opts.report.text.trim()) return box;
-    box.addChild(new Text(theme.fg("dim", "── report ──"), 0, 0));
-    box.addChild(opts.renderText(opts.report.text));
+    if (!(last?.kind === "text" && last.text.trim() === opts.report.text.trim())) {
+      box.addChild(new Text(theme.fg("dim", "── report ──"), 0, 0));
+      box.addChild(opts.renderText(opts.report.text));
+    }
   }
   return box;
 }

package/src/sidekick-widget.ts

@@ -1,3 +0,0 @@
-export function shouldShowSidekickWidget(busy: boolean, attached: boolean): boolean {
-  return busy && !attached;
-}