@pi-unipi/fusion 2.19.0 → 2.19.1

package/README.md

@@ -95,7 +95,11 @@ default; `block:false` returns immediately and delivers a
 handoff. 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.
+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({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.0",
+  "version": "2.19.1",
   "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.0",
-    "@pi-unipi/subagents": "2.19.0"
+    "@pi-unipi/core": "2.19.1",
+    "@pi-unipi/subagents": "2.19.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/src/index.ts

@@ -40,6 +40,8 @@ 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";
 
 export const MODEL_COMMAND = `${UNIPI_PREFIX}model`;
 export const PRESET_COMMAND = `${UNIPI_PREFIX}fusion-preset`;
@@ -118,6 +120,10 @@ 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;
 
   function identity(ctx: ExtensionContext): FusionIdentity {
     const reg = registryOf(ctx);
@@ -161,8 +167,79 @@ 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);
+    if (lastCtx) {
+      publishStatus(lastCtx);
+      publishSidekickWidgetLater();
+    }
   }
 
   function leadSessionId(ctx: ExtensionContext): string {
@@ -186,6 +263,8 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   }
 
   function stopRuntime(): void {
+    clearSidekickWidget();
+    attached = false;
     runtime?.kill();
     runtime = undefined;
     leadToolCalls = 0;
@@ -206,8 +285,20 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   registerFusionTools(pi, {
     getRuntime,
-    onReport: (ctx) => publishStatus(ctx),
+    onReport: (ctx) => {
+      attached = false;
+      clearSidekickWidget();
+      publishStatus(ctx);
+    },
     onHandoffStart: (ctx) => publishStatus(ctx),
+    onAttach: () => {
+      attached = true;
+      clearSidekickWidget();
+    },
+    onDetach: () => {
+      attached = false;
+      publishSidekickWidgetLater();
+    },
   });
   pi.registerCommand("unipi:fusion-stats", {
     description: "Estimated Fusion savings (sidekick tokens priced at lead rates)",

package/src/sidekick-widget.ts

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

package/src/tools.ts

@@ -1,8 +1,8 @@
-import { Markdown, Text, type Component } from "@earendil-works/pi-tui";
-import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+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 { frameSidekick, renderSidekickTranscript, type ThemeLike as TranscriptTheme } from "./transcript.js";
+import { duration, markdownText, renderSidekickTranscript, sidekickWorkingHeader } from "./transcript.js";
 
 const SidekickParams = Type.Object({
   message: Type.String({ description: "A concrete implementation or verification brief for the sidekick" }),
@@ -18,10 +18,8 @@ export interface FusionToolDeps {
   getRuntime: (ctx: ExtensionContext) => SidekickRuntime | undefined;
   onReport?: (ctx: ExtensionContext, report: HandoffReport) => void;
   onHandoffStart?: (ctx: ExtensionContext) => void;
-}
-
-function duration(ms: number): string {
-  return `${(ms / 1000).toFixed(1)}s`;
+  onAttach?: (ctx: ExtensionContext) => void;
+  onDetach?: (ctx: ExtensionContext) => void;
 }
 
 function firstLine(value: string): string {
@@ -100,16 +98,26 @@ function completionMessage(report: HandoffReport): { customType: string; content
 
 type ThemeLike = {
   fg: (color: string, text: string) => string;
-  bg: (color: string, text: string) => string;
   bold: (text: string) => string;
 };
 
-function transcriptTheme(theme: ThemeLike): TranscriptTheme {
-  return { fg: (color, text) => theme.fg(color, text), bold: (text) => theme.bold(text) };
-}
-
-function markdownText(markdown: string): Markdown {
-  return new Markdown(markdown, 0, 0, getMarkdownTheme());
+// 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.
+const HANDOFF_ID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+function displayText(text: string): string {
+  return text
+    .replace(/<\/?subagent_completion_notification[^>]*>/g, "")
+    .replace(/use `?read_subagent`?[^.\n]*\.?/gi, "")
+    .replace(HANDOFF_ID, "")
+    .replace(/agent_id[ =]?"?"?/g, "")
+    .replace(/read_subagent\([^)]*\)/g, "read_subagent")
+    .replace(/\(\s*\)/g, "")
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/\bHandoff\s*(?=(is|was|failed|aborted|started)\b)/g, "The handoff ")
+    .replace(/ for\s*\./g, ".")
+    .replace(/ +$/gm, "")
+    .trim();
 }
 
 function contentText(content: unknown): string {
@@ -117,18 +125,29 @@ function contentText(content: unknown): string {
   return content.map((part) => typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
 }
 
+function backgroundComponent(theme: ThemeLike): Component {
+  return new Text(`${theme.fg("accent", theme.bold("◆ sidekick"))} ${theme.fg("dim", "· continuing in background")}`, 0, 0);
+}
+
+type ToolDetails = Partial<HandoffReport> & { progress?: HandoffProgress; background?: boolean; id?: string };
+
+function reportHeader(theme: ThemeLike, label: string, report: HandoffReport | undefined): string {
+  const status = report?.status ?? "done";
+  return `${theme.fg(status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`${label} ${status}`))} ${theme.fg("dim", report ? `· ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)} · in ${String(report.usage.input)} / out ${String(report.usage.output)} tokens` : "")}`;
+}
+
 function renderToolTranscript(result: { content?: unknown; details?: unknown; isError?: boolean }, options: { expanded?: boolean }, theme: ThemeLike, label: "sidekick" | "read_subagent"): Component {
-  const details = result.details as (HandoffReport & { progress?: HandoffProgress }) | { progress?: HandoffProgress } | undefined;
+  const details = result.details as ToolDetails | undefined;
+  if (details?.background === true) return backgroundComponent(theme);
+  const hasProgress = details !== undefined && "progress" in details;
   const progress = details?.progress;
+  if (hasProgress && progress === undefined) return backgroundComponent(theme);
   const report = progress ? undefined : details as HandoffReport | undefined;
   const events = progress?.events ?? report?.events;
   const partial = progress !== undefined;
-  const status = partial ? "working" : report?.status === "completed" && !result.isError ? "completed" : "error";
-  if (!events) return frameSidekick(theme, status, new Text(contentText(result.content), 0, 0));
-  const header = partial
-    ? `${theme.fg("accent", theme.bold(`◆ ${label} working`))} ${theme.fg("dim", `· ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)}`)}`
-    : `${theme.fg(report?.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`${label} ${report?.status ?? "done"}`))} ${theme.fg("dim", report ? `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)} · in ${String(report.usage.input)} / out ${String(report.usage.output)} tokens` : "")}`;
-  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+  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, {
     events,
     droppedEvents: progress?.droppedEvents,
     header,
@@ -136,20 +155,19 @@ function renderToolTranscript(result: { content?: unknown; details?: unknown; is
     isPartial: partial,
     report,
     renderText: markdownText,
-  }));
+  });
 }
 
 function renderCompletionCard(theme: ThemeLike, report: HandoffReport | undefined): Component {
-  const status = report?.status === "completed" ? "completed" : "error";
-  if (!report) return frameSidekick(theme, "error", new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0));
-  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+  if (!report) return new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0);
+  return renderSidekickTranscript(theme, {
     events: report.events ?? [],
-    header: `${theme.fg(report.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`sidekick ${report.status}`))} ${theme.fg("dim", `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)}`)}`,
+    header: reportHeader(theme, "sidekick", report),
     expanded: false,
     isPartial: false,
     report,
     renderText: markdownText,
-  }));
+  });
 }
 
 export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): void {
@@ -161,7 +179,7 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     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) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ sidekick"))} ${theme.fg("dim", firstLine(String(args.message)).slice(0, 100))}`, 0, 0)),
+    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) {
       const runtime = deps.getRuntime(ctx);
@@ -174,17 +192,20 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
           deps.onReport?.(ctx, report);
           pi.sendMessage(completionMessage(report) as never, { deliverAs: "followUp", triggerTurn: true } as never);
         }).catch(() => undefined);
-        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.`);
+        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);
       const waited = await waitForReport(runtime, handoff.id, handoff.done, signal, ctx, onUpdate ? (update) => onUpdate(update as never) : undefined);
       if (waited.report) {
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      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);
-      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${handoff.id}) was working. The handoff continues in the background. Act on the user's message first, then call read_subagent({agent_id:"${handoff.id}", block:true}) to collect the report or sidekick({message}) to redirect it.\n${waited.interrupted}`);
-      return result(`Handoff ${handoff.id} is still running.\n${progressText(runtime, handoff.id)}`);
+      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${handoff.id}) was working. The handoff continues in the background. Act on the user's message first, then call read_subagent({agent_id:"${handoff.id}", block:true}) to collect the report or sidekick({message}) to redirect it.\n${waited.interrupted}`, { progress: runtime.progress(handoff.id), id: handoff.id });
+      return result(`Handoff ${handoff.id} is still running.\n${progressText(runtime, handoff.id)}`, { progress: runtime.progress(handoff.id), id: handoff.id });
     },
   });
 
@@ -194,7 +215,7 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     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) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ read_subagent"))} ${theme.fg("dim", args.agent_id ?? "latest")}`, 0, 0)),
+    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) {
       const runtime = deps.getRuntime(ctx);
@@ -205,17 +226,19 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
       const selected = runtime.reports.get(id);
       if (selected) 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)}`);
+      if (params.block !== true) return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`, { progress: runtime.progress(id), id });
+      deps.onAttach?.(ctx);
       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) {
         deps.onReport?.(ctx, waited.report);
         return result(reportText(waited.report), waited.report, waited.report.status !== "completed");
       }
+      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);
-      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${id}) was working.\n${waited.interrupted}`);
-      return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`);
+      if (waited.interrupted) return result(`A user message arrived while the sidekick (agent_id ${id}) was working.\n${waited.interrupted}`, { progress: runtime.progress(id), id });
+      return result(`Handoff ${id} is still running.\n${progressText(runtime, id)}`, { progress: runtime.progress(id), id });
     },
   });
 

package/src/transcript.ts

@@ -1,11 +1,24 @@
-import { Box, Container, Text, type Component } from "@earendil-works/pi-tui";
-import type { SidekickEvent } from "./sidekick-runtime.js";
+import { Box, Container, Markdown, Text, type Component } from "@earendil-works/pi-tui";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { HandoffProgress, SidekickEvent } from "./sidekick-runtime.js";
 
 export interface ThemeLike {
   fg: (color: string, text: string) => string;
   bold: (text: string) => string;
 }
 
+export function duration(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+export function markdownText(markdown: string): Component {
+  return new Markdown(markdown, 0, 0, getMarkdownTheme());
+}
+
+export function sidekickWorkingHeader(theme: ThemeLike, progress: Pick<HandoffProgress, "toolCalls" | "startedAt">, label = "sidekick"): string {
+  return `${theme.fg("accent", theme.bold(`◆ ${label} working`))} ${theme.fg("dim", `· ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)}`)}`;
+}
+
 export class RailComponent implements Component {
   constructor(private readonly inner: Component, private readonly rail: string) {}