@xzzpig/pi-subagents 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +40 -0
  2. package/agents/oracle.md +7 -5
  3. package/agents/researcher.md +1 -1
  4. package/agents/reviewer.md +2 -2
  5. package/agents/scout.md +1 -1
  6. package/agents/worker.md +1 -1
  7. package/docs/agents.md +2 -0
  8. package/docs/configuration.md +47 -3
  9. package/docs/extension-api.md +36 -0
  10. package/docs/missions.md +1 -1
  11. package/docs/observability.md +16 -0
  12. package/docs/tool-reference.md +19 -2
  13. package/docs/workflows.md +2 -2
  14. package/package.json +4 -4
  15. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  16. package/skills/pi-subagents/references/execution-controls.md +5 -4
  17. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  18. package/skills/pi-subagents/references/prompting-and-roles.md +31 -15
  19. package/src/agents/agent-serializer.ts +2 -0
  20. package/src/agents/agents.ts +10 -0
  21. package/src/api/external-runs.ts +174 -84
  22. package/src/api/preflight.ts +12 -6
  23. package/src/extension/config.ts +33 -0
  24. package/src/extension/index.ts +48 -5
  25. package/src/extension/public-execution.ts +3 -1
  26. package/src/extension/rpc.ts +5 -1
  27. package/src/extension/schemas.ts +2 -1
  28. package/src/extension/tool-description.ts +4 -2
  29. package/src/inspectors/herdr/actions.ts +3 -7
  30. package/src/inspectors/herdr/project-panes.ts +2 -6
  31. package/src/inspectors/herdr/shell-command.ts +16 -0
  32. package/src/intercom/intercom-bridge.ts +2 -3
  33. package/src/intercom/native-supervisor-channel.ts +19 -42
  34. package/src/missions/goal-driver.ts +3 -1
  35. package/src/runs/background/active-run-index.ts +71 -1
  36. package/src/runs/background/async-execution.ts +49 -7
  37. package/src/runs/background/async-job-tracker.ts +1 -0
  38. package/src/runs/background/async-resume.ts +3 -5
  39. package/src/runs/background/async-status-snapshot.ts +277 -0
  40. package/src/runs/background/async-status.ts +8 -3
  41. package/src/runs/background/chain-root-attachment.ts +2 -2
  42. package/src/runs/background/completion-replay.ts +11 -1
  43. package/src/runs/background/fleet-view.ts +3 -1
  44. package/src/runs/background/result-files.ts +437 -0
  45. package/src/runs/background/result-watcher.ts +188 -41
  46. package/src/runs/background/retained-children.ts +69 -20
  47. package/src/runs/background/run-id-resolver.ts +30 -24
  48. package/src/runs/background/run-status.ts +7 -2
  49. package/src/runs/background/scheduled-runs.ts +54 -28
  50. package/src/runs/background/stale-run-reconciler.ts +27 -13
  51. package/src/runs/background/subagent-runner.ts +294 -32
  52. package/src/runs/background/subagent-wait.ts +2 -0
  53. package/src/runs/background/wait-completions.ts +5 -2
  54. package/src/runs/foreground/async-dismiss-action.ts +2 -1
  55. package/src/runs/foreground/chain-execution.ts +16 -0
  56. package/src/runs/foreground/execution.ts +219 -15
  57. package/src/runs/foreground/subagent-executor.ts +114 -28
  58. package/src/runs/shared/completion-guard.ts +96 -6
  59. package/src/runs/shared/external-cli-runner.ts +4 -0
  60. package/src/runs/shared/model-fallback.ts +16 -2
  61. package/src/runs/shared/nested-events.ts +66 -62
  62. package/src/runs/shared/orca-progress-tabs.ts +375 -0
  63. package/src/runs/shared/parallel-utils.ts +2 -0
  64. package/src/runs/shared/subagent-control.ts +15 -0
  65. package/src/runs/shared/subagent-prompt-runtime.ts +1 -9
  66. package/src/runs/shared/subagent-startup-retry.ts +12 -0
  67. package/src/runs/shared/tool-timeout.ts +93 -0
  68. package/src/shared/types.ts +29 -2
  69. package/src/slash/slash-commands.ts +34 -25
  70. package/src/slash/slash-live-state.ts +3 -0
  71. package/src/tui/fleet-status.ts +160 -45
  72. package/src/tui/fleet.ts +145 -16
  73. package/src/tui/mouse-events.ts +42 -0
  74. package/src/tui/render.ts +41 -10
  75. package/src/workflows/chat-progress.ts +6 -4
  76. package/src/workflows/scripted-workflow.ts +227 -70
package/src/tui/fleet.ts CHANGED
@@ -3,12 +3,14 @@ import * as path from "node:path";
3
3
  import type { AgentToolResult } from "@earendil-works/pi-agent-core";
4
4
  import { getMarkdownTheme, type ExtensionContext } from "@earendil-works/pi-coding-agent";
5
5
  import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component, type MarkdownTheme } from "@earendil-works/pi-tui";
6
+ import { snapshotExternalRuns, type ExternalRun } from "../api/external-runs.ts";
6
7
  import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
7
8
  import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../shared/formatters.ts";
8
9
  import { DIRS, type AsyncJobState, type Details, type FleetKeybindingAction, type FleetKeybindingsConfig, type ForegroundChildControl, type ForegroundResumeChild, type ForegroundResumeRun, type ForegroundRunControl, type SubagentState } from "../shared/types.ts";
9
10
  import { decodeUtf8Tail } from "../shared/utf8.ts";
10
11
  import { readStatus } from "../shared/utils.ts";
11
12
  import { formatAsyncRunTranscript } from "../runs/background/fleet-view.ts";
13
+ import { parseMouseWheelEvent } from "./mouse-events.ts";
12
14
  import { listAsyncRuns, type AsyncRunSummary } from "../runs/background/async-status.ts";
13
15
  import { steerAsyncRun } from "../runs/foreground/async-steering-action.ts";
14
16
  import type { SteerDeliveryMode } from "../runs/background/control-channel.ts";
@@ -20,6 +22,8 @@ import { handleHerdrInspectorAction } from "../inspectors/herdr/actions.ts";
20
22
  import { getLivePromptAudit, type LivePromptAudit, type PromptAuditView } from "../runs/foreground/prompt-audit.ts";
21
23
 
22
24
  const REFRESH_MS = 750;
25
+ const MIN_REFRESH_MS = 250;
26
+ const WHEEL_SCROLL_LINES = 3;
23
27
  const MAX_RECENT_ASYNC_RUNS = 20;
24
28
  const MAX_FLEET_HISTORY_CANDIDATES = 100;
25
29
  const TRANSCRIPT_LINES = 200;
@@ -77,6 +81,7 @@ export type FleetItem = (
77
81
  | { key: string; kind: "foreground-active"; runId: string; index?: number; agent: string; state: "running"; updatedAt: number; control: ForegroundRunControl; activeChild?: ForegroundChildControl }
78
82
  | { key: string; kind: "foreground-recent"; runId: string; index: number; agent: string; state: ForegroundResumeChild["status"]; updatedAt: number; run: ForegroundResumeRun; child: ForegroundResumeChild }
79
83
  | { key: string; kind: "async"; runId: string; index?: number; agent: string; state: string; updatedAt: number; run: AsyncRunSummary; step?: AsyncStep }
84
+ | { key: string; kind: "external"; runId: string; agent: string; state: ExternalRun["state"]; updatedAt: number; run: ExternalRun }
80
85
  ) & { description?: string };
81
86
 
82
87
  export interface FleetSnapshot {
@@ -186,8 +191,13 @@ export function collectFleetSnapshot(
186
191
  ): FleetSnapshot {
187
192
  const items: FleetItem[] = [];
188
193
  const activeForegroundIds = new Set<string>();
194
+ const trackedJobs = state.fleetJobs ?? state.asyncJobs;
195
+ const workflowParentIds = new Set([...trackedJobs.values()]
196
+ .filter((job) => job.mode === "workflow" && belongsToCurrentSession(job.sessionId, state.currentSessionId))
197
+ .map((job) => job.asyncId));
189
198
  for (const control of [...state.foregroundControls.values()].sort((left, right) => right.updatedAt - left.updatedAt)) {
190
199
  activeForegroundIds.add(control.runId);
200
+ if (control.parentWorkflowRunId && workflowParentIds.has(control.parentWorkflowRunId)) continue;
191
201
  if (control.activeChildren) {
192
202
  for (const child of [...control.activeChildren.values()].sort((left, right) => left.index - right.index)) {
193
203
  items.push({
@@ -222,7 +232,7 @@ export function collectFleetSnapshot(
222
232
  try {
223
233
  let runs: AsyncRunSummary[];
224
234
  const descriptions = new Map<string, string>();
225
- const tracked = [...(state.fleetJobs ?? state.asyncJobs).values()]
235
+ const tracked = [...trackedJobs.values()]
226
236
  .filter((job) => belongsToCurrentSession(job.sessionId, state.currentSessionId));
227
237
  const byUpdate = (left: AsyncJobState, right: AsyncJobState) => (right.updatedAt ?? right.startedAt ?? 0) - (left.updatedAt ?? left.startedAt ?? 0);
228
238
  const active = tracked.filter((job) => job.status === "queued" || job.status === "running").sort(byUpdate);
@@ -255,6 +265,26 @@ export function collectFleetSnapshot(
255
265
  error = cause instanceof Error ? cause.message : String(cause);
256
266
  }
257
267
 
268
+ if (state.currentSessionId) {
269
+ try {
270
+ for (const run of snapshotExternalRuns(state.currentSessionId, { ignoreMalformed: true, onMalformedRecord: (message) => console.warn(`[pi-subagents] Removed ${message}`) })) {
271
+ items.push({
272
+ key: `external:${run.id}`,
273
+ kind: "external",
274
+ runId: run.id,
275
+ agent: run.label,
276
+ state: run.state,
277
+ updatedAt: run.updatedAt ?? run.endedAt ?? run.startedAt,
278
+ run,
279
+ ...(run.currentAction ? { description: run.currentAction } : {}),
280
+ });
281
+ }
282
+ } catch (cause) {
283
+ const message = `Failed to inspect external jobs: ${cause instanceof Error ? cause.message : String(cause)}`;
284
+ error = error ? `${error}; ${message}` : message;
285
+ }
286
+ }
287
+
258
288
  const recentForeground = [...(state.foregroundRuns?.values() ?? [])]
259
289
  .filter((run) => belongsToCurrentSession(run.sessionId, state.currentSessionId) && !activeForegroundIds.has(run.runId))
260
290
  .sort((left, right) => right.updatedAt - left.updatedAt);
@@ -276,6 +306,27 @@ export function collectFleetSnapshot(
276
306
  return { items, ...(error ? { error } : {}) };
277
307
  }
278
308
 
309
+ function visibleWorkflowParentKeyForForegroundKey(state: SubagentState, key: string, items: FleetItem[]): string | undefined {
310
+ for (const control of state.foregroundControls.values()) {
311
+ if (!control.parentWorkflowRunId) continue;
312
+ let matches = false;
313
+ if (control.activeChildren) {
314
+ for (const child of control.activeChildren.values()) {
315
+ if (`foreground-active:${control.runId}:${child.index}` === key) {
316
+ matches = true;
317
+ break;
318
+ }
319
+ }
320
+ } else {
321
+ matches = `foreground-active:${control.runId}:${control.currentIndex ?? 0}` === key;
322
+ }
323
+ if (!matches) continue;
324
+ const parentKey = `async:${control.parentWorkflowRunId}`;
325
+ return items.some((item) => item.key === parentKey) ? parentKey : undefined;
326
+ }
327
+ return undefined;
328
+ }
329
+
279
330
  function statusGlyph(item: FleetItem, theme: Theme): string {
280
331
  if (item.state === "running") return theme.fg("accent", "●");
281
332
  if (item.state === "queued" || item.state === "pending") return theme.fg("muted", "◦");
@@ -424,6 +475,11 @@ function foregroundRecentDetail(item: Extract<FleetItem, { kind: "foreground-rec
424
475
  return lines.filter((line): line is string => line !== undefined);
425
476
  }
426
477
 
478
+ function externalElapsedEnd(run: ExternalRun): number {
479
+ const terminal = run.state !== "queued" && run.state !== "running";
480
+ return terminal ? (run.endedAt ?? run.updatedAt ?? Date.now()) : Date.now();
481
+ }
482
+
427
483
  function asyncDetail(item: Extract<FleetItem, { kind: "async" }>): string[] {
428
484
  const status = readStatus(item.run.asyncDir);
429
485
  if (status) {
@@ -444,13 +500,36 @@ function asyncDetail(item: Extract<FleetItem, { kind: "async" }>): string[] {
444
500
  ].filter((line): line is string => line !== undefined);
445
501
  }
446
502
 
503
+ function externalDetail(item: Extract<FleetItem, { kind: "external" }>): string[] {
504
+ return [
505
+ `Run: ${item.runId}`,
506
+ "Source: external · display-only",
507
+ `Owner: ${item.run.source}`,
508
+ `State: ${item.state}`,
509
+ `Started: ${new Date(item.run.startedAt).toISOString()}`,
510
+ item.run.updatedAt !== undefined ? `Updated: ${new Date(item.run.updatedAt).toISOString()}` : undefined,
511
+ item.run.endedAt !== undefined ? `Ended: ${new Date(item.run.endedAt).toISOString()}` : undefined,
512
+ `Elapsed: ${formatDuration(Math.max(0, externalElapsedEnd(item.run) - item.run.startedAt))}`,
513
+ item.run.currentAction ? `Current action: ${item.run.currentAction}` : undefined,
514
+ item.run.reportPath ? `Report path: ${item.run.reportPath}` : undefined,
515
+ item.run.transcriptPath ? `Transcript path: ${item.run.transcriptPath}` : undefined,
516
+ "",
517
+ "Preview",
518
+ item.run.preview ?? "(no preview supplied)",
519
+ "",
520
+ "The owning extension controls execution, persistence, cancellation, and results.",
521
+ ].filter((line): line is string => line !== undefined);
522
+ }
523
+
447
524
  function detailLines(item: FleetItem | undefined, error: string | undefined, state: SubagentState): string[] {
448
- if (!item) return [error ? `Fleet scan failed: ${error}` : "No current-session foreground or recent async children.", "", "New runs appear here automatically while this inspector remains open."];
525
+ if (!item) return [error ? `Fleet scan failed: ${error}` : "No current-session Fleet jobs.", "", "New jobs appear here automatically while this inspector remains open."];
449
526
  const lines = item.kind === "foreground-active"
450
527
  ? foregroundActiveDetail(item, state)
451
528
  : item.kind === "foreground-recent"
452
529
  ? foregroundRecentDetail(item, state)
453
- : asyncDetail(item);
530
+ : item.kind === "external"
531
+ ? externalDetail(item)
532
+ : asyncDetail(item);
454
533
  if (error) lines.unshift(`Fleet scan warning: ${error}`, "");
455
534
  return lines;
456
535
  }
@@ -478,6 +557,7 @@ function fleetArtifactsRoot(state: SubagentState, cwd: string): string {
478
557
  }
479
558
 
480
559
  function transcriptTarget(item: FleetItem, state: SubagentState): { path: string; trustedRoots: string[] } | undefined {
560
+ if (item.kind === "external") return undefined;
481
561
  if (item.kind === "foreground-active") {
482
562
  const artifactsRoot = fleetArtifactsRoot(state, item.control.cwd ?? state.baseCwd);
483
563
  return {
@@ -522,10 +602,12 @@ function itemContext(item: FleetItem): string | undefined {
522
602
  }
523
603
 
524
604
  function itemMode(item: FleetItem): string {
605
+ if (item.kind === "external") return "display-only";
525
606
  return item.kind === "foreground-active" ? item.control.mode : item.run.mode;
526
607
  }
527
608
 
528
609
  function itemSource(item: FleetItem): string {
610
+ if (item.kind === "external") return `external · ${item.run.source}`;
529
611
  if (item.kind === "async") return "background";
530
612
  return item.kind === "foreground-active" ? "foreground · live" : "foreground · recent";
531
613
  }
@@ -545,6 +627,8 @@ function itemStats(item: FleetItem): string[] {
545
627
  model = formatModelThinking(item.child.model, item.child.thinking) || undefined;
546
628
  tokens = item.child.tokens;
547
629
  tools = item.child.toolCount;
630
+ } else if (item.kind === "external") {
631
+ durationMs = Math.max(0, externalElapsedEnd(item.run) - item.run.startedAt);
548
632
  } else {
549
633
  model = formatModelThinking(item.step?.model, item.step?.thinking) || undefined;
550
634
  tokens = item.step?.tokens?.total ?? (item.index === undefined ? item.run.totalTokens?.total : undefined);
@@ -564,7 +648,7 @@ function itemStats(item: FleetItem): string[] {
564
648
  function structuredHeader(item: FleetItem, width: number, theme: Theme, conversationState: string, promptSummary?: string): string[] {
565
649
  const lines: string[] = [];
566
650
  lines.push(rightAligned(` ${statusGlyph(item, theme)} ${theme.bold(item.agent)}`, theme.fg("dim", item.state), width));
567
- const child = item.index !== undefined ? ` · child ${item.index + 1}` : "";
651
+ const child = "index" in item && item.index !== undefined ? ` · child ${item.index + 1}` : "";
568
652
  const context = itemContext(item);
569
653
  const identity = `${itemSource(item)} · ${item.runId.slice(0, 8)}${child} · ${itemMode(item)}${context ? ` ${context}` : ""}`;
570
654
  lines.push(` ${theme.fg("dim", identity)}`);
@@ -618,6 +702,7 @@ export class SubagentFleetComponent implements Component {
618
702
  private detailLineCount = 0;
619
703
  private detailViewportHeight = 8;
620
704
  private bodyHeight = 8;
705
+ private lastRosterWidth: number | undefined;
621
706
  private expandedTools = false;
622
707
  private promptAuditOpen = false;
623
708
  private promptAuditView: PromptAuditView = "authored";
@@ -629,7 +714,8 @@ export class SubagentFleetComponent implements Component {
629
714
  private actionBusy = false;
630
715
  private transcriptCache: FleetTranscriptCache | undefined;
631
716
  private disposed = false;
632
- private readonly timer: ReturnType<typeof setInterval>;
717
+ private refreshTimer: ReturnType<typeof setTimeout> | undefined;
718
+ private readonly refreshMs: number;
633
719
  private readonly tui: FleetTui;
634
720
  private readonly theme: Theme;
635
721
  private readonly markdownTheme: MarkdownTheme;
@@ -652,20 +738,41 @@ export class SubagentFleetComponent implements Component {
652
738
  this.done = done;
653
739
  this.options = options;
654
740
  this.keybindings = resolveFleetKeybindings(options.fleetKeybindings);
741
+ this.refreshMs = Math.max(MIN_REFRESH_MS, options.refreshMs ?? REFRESH_MS);
655
742
  this.selectedKey = options.initialKey;
656
743
  this.refresh();
657
- this.timer = setInterval(() => {
744
+ this.scheduleRefresh();
745
+ }
746
+
747
+ private scheduleRefresh(): void {
748
+ if (this.disposed || this.refreshTimer) return;
749
+ this.refreshTimer = setTimeout(() => {
750
+ this.refreshTimer = undefined;
658
751
  if (this.disposed) return;
659
- this.invalidate();
660
- this.tui.requestRender();
661
- }, options.refreshMs ?? REFRESH_MS);
662
- this.timer.unref?.();
752
+ try {
753
+ this.invalidate();
754
+ this.tui.requestRender();
755
+ } finally {
756
+ this.scheduleRefresh();
757
+ }
758
+ }, this.refreshMs);
759
+ this.refreshTimer.unref?.();
760
+ }
761
+
762
+ private stopRefresh(): void {
763
+ this.disposed = true;
764
+ if (this.refreshTimer) clearTimeout(this.refreshTimer);
765
+ this.refreshTimer = undefined;
663
766
  }
664
767
 
665
768
  private refresh(): void {
666
769
  const previousKey = this.snapshot.items[this.selected]?.key ?? this.selectedKey;
667
770
  this.snapshot = collectFleetSnapshot(this.state, this.options);
668
- const preserved = previousKey ? this.snapshot.items.findIndex((item) => item.key === previousKey) : -1;
771
+ let preserved = previousKey ? this.snapshot.items.findIndex((item) => item.key === previousKey) : -1;
772
+ if (preserved < 0 && previousKey) {
773
+ const parentKey = visibleWorkflowParentKeyForForegroundKey(this.state, previousKey, this.snapshot.items);
774
+ if (parentKey) preserved = this.snapshot.items.findIndex((item) => item.key === parentKey);
775
+ }
669
776
  this.selected = preserved >= 0 ? preserved : Math.min(this.selected, Math.max(0, this.snapshot.items.length - 1));
670
777
  this.selectedKey = this.snapshot.items[this.selected]?.key;
671
778
  }
@@ -725,6 +832,7 @@ export class SubagentFleetComponent implements Component {
725
832
  private selectedAsyncAction(): { item: Extract<FleetItem, { kind: "async" }> } | { reason: string } {
726
833
  const item = this.snapshot.items[this.selected];
727
834
  if (!item) return { reason: "No child is selected." };
835
+ if (item.kind === "external") return { reason: "External jobs are display-only and remain controlled by their owning extension." };
728
836
  if (item.kind !== "async") return { reason: "Fleet controls are available for current-session top-level async runs only." };
729
837
  if (!isActionableAsyncState(item.run.state) || !isActionableAsyncState(item.state)) return { reason: `Selected child is ${item.state}; controls require a running or queued async child.` };
730
838
  return { item };
@@ -733,6 +841,7 @@ export class SubagentFleetComponent implements Component {
733
841
  private selectedHerdrInspectAction(): { runId: string; asyncDir: string; index?: number } | { reason: string } {
734
842
  const item = this.snapshot.items[this.selected];
735
843
  if (!item) return { reason: "No child is selected." };
844
+ if (item.kind === "external") return { reason: "External jobs are display-only and have no Herdr controls." };
736
845
  if (item.kind === "async") {
737
846
  if (!isActionableAsyncState(item.run.state) || !isActionableAsyncState(item.state)) return { reason: `Selected child is ${item.state}; controls require a running or queued async child.` };
738
847
  return { runId: item.runId, asyncDir: item.run.asyncDir, ...(item.index !== undefined ? { index: item.index } : {}) };
@@ -798,6 +907,21 @@ export class SubagentFleetComponent implements Component {
798
907
  }
799
908
 
800
909
  handleInput(data: string): void {
910
+ const wheel = parseMouseWheelEvent(data);
911
+ if (wheel) {
912
+ // While editing draft text, ignore the wheel to avoid surprising scroll jumps.
913
+ if (this.steerDraft !== undefined || this.redoGuidanceDraft !== undefined) return;
914
+ const overRoster = this.lastRosterWidth !== undefined && wheel.x <= this.lastRosterWidth;
915
+ if (this.promptAuditOpen) {
916
+ if (overRoster) this.movePromptSelection(wheel.direction);
917
+ else this.scrollDetail(wheel.direction * WHEEL_SCROLL_LINES);
918
+ } else if (overRoster) {
919
+ this.moveSelection(wheel.direction);
920
+ } else {
921
+ this.scrollDetail(wheel.direction * WHEEL_SCROLL_LINES);
922
+ }
923
+ return;
924
+ }
801
925
  if (this.promptAuditOpen && this.redoGuidanceDraft !== undefined) {
802
926
  if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) {
803
927
  this.resetActionInput();
@@ -928,6 +1052,7 @@ export class SubagentFleetComponent implements Component {
928
1052
  return;
929
1053
  }
930
1054
  if (matchesFleetAction(data, this.keybindings, "close")) {
1055
+ this.stopRefresh();
931
1056
  this.done(undefined);
932
1057
  return;
933
1058
  }
@@ -1102,6 +1227,7 @@ export class SubagentFleetComponent implements Component {
1102
1227
  const rows = this.tui.terminal?.rows ?? 32;
1103
1228
  this.bodyHeight = Math.max(2, Math.floor(rows * 0.85) - 6);
1104
1229
  const rosterWidth = Math.max(22, Math.min(46, Math.floor((innerWidth - 1) * 0.38)));
1230
+ this.lastRosterWidth = rosterWidth;
1105
1231
  const detailWidth = Math.max(1, innerWidth - rosterWidth - 1);
1106
1232
  const roster = this.rosterLines(rosterWidth);
1107
1233
  const detail = this.wrappedDetail(detailWidth);
@@ -1117,7 +1243,9 @@ export class SubagentFleetComponent implements Component {
1117
1243
  ];
1118
1244
  const lines = [this.theme.fg("border", `╭${"─".repeat(innerWidth)}╮`)];
1119
1245
  const selected = this.snapshot.items[this.selected];
1120
- const title = ` ${this.theme.bold("Subagent fleet inspector")} ${this.theme.fg("dim", "· live controls")}`;
1246
+ const title = selected?.kind === "external"
1247
+ ? ` ${this.theme.bold("Fleet inspector")} ${this.theme.fg("dim", "· external display-only")}`
1248
+ : ` ${this.theme.bold("Subagent fleet inspector")} ${this.theme.fg("dim", "· live controls")}`;
1121
1249
  const selectedStatus = selected
1122
1250
  ? `${statusGlyph(selected, this.theme)} ${selected.agent} · ${selected.state} `
1123
1251
  : this.theme.fg("dim", "no children ");
@@ -1135,8 +1263,10 @@ export class SubagentFleetComponent implements Component {
1135
1263
  lines.push(this.theme.fg("border", `├${"─".repeat(rosterWidth)}┴${"─".repeat(detailWidth)}┤`));
1136
1264
  const position = this.snapshot.items.length ? `${this.selected + 1}/${this.snapshot.items.length}` : "0/0";
1137
1265
  const footer = this.promptAuditOpen
1138
- ? ` j/k child · 1/2/3 view · g redo with guidance · c copy · Esc close Prompt Audit · ${position}`
1139
- : ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} agent · p Prompt Audit · ${bindingLabel(this.keybindings, "inspect")} Herdr · ${bindingLabel(this.keybindings, "steer")} steer · ${bindingLabel(this.keybindings, "stop")} stop · ${bindingLabel(this.keybindings, "toggleTools")} tools · ${bindingLabel(this.keybindings, "refresh")} refresh · ${bindingLabel(this.keybindings, "close")} close · ${position}`;
1266
+ ? ` j/k child · 1/2/3 view · g redo with guidance · c copy · wheel ↑↓ · Esc close Prompt Audit · ${position}`
1267
+ : selected?.kind === "external"
1268
+ ? ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} job · display-only · ${bindingLabel(this.keybindings, "refresh")} refresh · wheel ↑↓ · ${bindingLabel(this.keybindings, "close")} close · ${position}`
1269
+ : ` ${bindingLabel(this.keybindings, "selectUp")}/${bindingLabel(this.keybindings, "selectDown")} agent · p Prompt Audit · ${bindingLabel(this.keybindings, "inspect")} Herdr · ${bindingLabel(this.keybindings, "steer")} steer · ${bindingLabel(this.keybindings, "stop")} stop · ${bindingLabel(this.keybindings, "toggleTools")} tools · ${bindingLabel(this.keybindings, "refresh")} refresh · wheel ↑↓ · ${bindingLabel(this.keybindings, "close")} close · ${position}`;
1140
1270
  lines.push(this.theme.fg("border", "│") + fit(this.theme.fg("dim", footer), innerWidth) + this.theme.fg("border", "│"));
1141
1271
  lines.push(this.theme.fg("border", `╰${"─".repeat(innerWidth)}╯`));
1142
1272
  return lines.map((line) => truncateToWidth(line, width));
@@ -1148,8 +1278,7 @@ export class SubagentFleetComponent implements Component {
1148
1278
  }
1149
1279
 
1150
1280
  dispose(): void {
1151
- this.disposed = true;
1152
- clearInterval(this.timer);
1281
+ this.stopRefresh();
1153
1282
  }
1154
1283
  }
1155
1284
 
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Minimal SGR/X10 mouse parsing for the fleet inspector.
3
+ *
4
+ * In fullscreen mode pi-tui owns terminal mouse modes (?1000h ?1002h ?1003h
5
+ * ?1006h) itself and forwards raw wheel events to a focused overlay's
6
+ * `handleInput` (the same mechanism pi-btw relies on). We therefore never
7
+ * write mouse enable/disable sequences here — we only parse the forwarded
8
+ * data. SGR encoding reports `ESC[<b;c;rM` (press) / `m` (release); X10
9
+ * reports `ESC[M` followed by three bytes (button, column + 32, row + 32).
10
+ * Wheel buttons carry the 64 bit; the low bits select the direction
11
+ * (0 = up, 1 = down). The 32 bit marks a button release (SGR wheel releases
12
+ * are 96/97), which we ignore so a motion-tracking terminal cannot
13
+ * double-scroll per notch.
14
+ */
15
+ export interface MouseWheelEvent {
16
+ /** -1 for wheel up, 1 for wheel down. */
17
+ direction: -1 | 1;
18
+ /** Zero-based terminal column where the wheel event occurred. */
19
+ x: number;
20
+ }
21
+
22
+ export function parseMouseWheelEvent(data: string): MouseWheelEvent | undefined {
23
+ const sgr = /^\x1b\[<(\d+);(\d+);(\d+)[Mm]$/.exec(data);
24
+ if (sgr) {
25
+ const buttonText = sgr[1];
26
+ const xText = sgr[2];
27
+ if (buttonText === undefined || xText === undefined) return undefined;
28
+ const button = Number.parseInt(buttonText, 10);
29
+ if ((button & 64) === 0 || (button & 32) === 32) return undefined;
30
+ const direction = button & 3;
31
+ if (direction !== 0 && direction !== 1) return undefined;
32
+ return { direction: direction === 0 ? -1 : 1, x: Number.parseInt(xText, 10) - 1 };
33
+ }
34
+ if (data.length === 6 && data.startsWith("\x1b[M")) {
35
+ const button = data.charCodeAt(3) - 32;
36
+ if ((button & 64) === 0 || (button & 32) === 32) return undefined;
37
+ const direction = button & 3;
38
+ if (direction !== 0 && direction !== 1) return undefined;
39
+ return { direction: direction === 0 ? -1 : 1, x: data.charCodeAt(4) - 33 };
40
+ }
41
+ return undefined;
42
+ }
package/src/tui/render.ts CHANGED
@@ -28,6 +28,7 @@ import { formatNestedAggregate } from "../runs/shared/nested-render.ts";
28
28
  import { aggregateStepStatus, formatActivityLabel, formatAgentRunningLabel, formatParallelOutcome } from "../shared/status-format.ts";
29
29
  import { contextModeBadge, contextModePrefix } from "../runs/shared/context-mode.ts";
30
30
  import { buildWorkflowChatProgressRows, type WorkflowChatProgressRow } from "../workflows/chat-progress.ts";
31
+ import { encodeAsyncStatusSnapshotWidget } from "../runs/background/async-status-snapshot.ts";
31
32
 
32
33
  type Theme = ExtensionContext["ui"]["theme"];
33
34
 
@@ -71,6 +72,22 @@ function liveDetailHintText(): string {
71
72
  return `Press ${liveDetailKeyText()} for live detail`;
72
73
  }
73
74
 
75
+ function foregroundSingleHintText(shortcut?: string): string {
76
+ if (!shortcut) return liveDetailHintText();
77
+ const label = shortcut
78
+ .split("+")
79
+ .map((part) => {
80
+ const normalized = part.trim().toLowerCase();
81
+ if (normalized === "ctrl") return "Ctrl";
82
+ if (normalized === "alt") return "Alt";
83
+ if (normalized === "shift") return "Shift";
84
+ if (normalized === "super") return "Super";
85
+ return normalized.length === 1 ? normalized.toUpperCase() : part.trim();
86
+ })
87
+ .join("+");
88
+ return `${liveDetailHintText()} · ${label} to run in background`;
89
+ }
90
+
74
91
  function getTermWidth(): number {
75
92
  return process.stdout.columns || 120;
76
93
  }
@@ -341,7 +358,7 @@ function visibleWorkflowRows(rows: WorkflowChatProgressRow[]): { rows: WorkflowC
341
358
  selected.add(row.key);
342
359
  };
343
360
  for (const row of [...rows].reverse()) {
344
- if (row.state === "failed") add(row);
361
+ if (row.state === "failed" || row.state === "detached") add(row);
345
362
  }
346
363
  for (const row of [...rows].reverse()) add(row);
347
364
  return {
@@ -1585,10 +1602,21 @@ export function renderWidget(ctx: ExtensionContext, jobs: AsyncJobState[]): void
1585
1602
  return;
1586
1603
  }
1587
1604
  if (!ctx.hasUI) return;
1605
+ if ((ctx as { mode?: string }).mode === "rpc") {
1606
+ ctx.ui.setWidget(WIDGET_KEY, encodeAsyncStatusSnapshotWidget(jobs));
1607
+ return;
1608
+ }
1588
1609
  ctx.ui.setWidget(WIDGET_KEY, buildWidgetComponent(jobs, ctx.ui.getToolsExpanded?.() ?? false));
1589
1610
  }
1590
1611
 
1591
- function renderSingleCompact(d: Details, r: Details["results"][number], theme: Theme, layout: MainWindowRenderLayout, frame?: number): Component {
1612
+ function renderSingleCompact(
1613
+ d: Details,
1614
+ r: Details["results"][number],
1615
+ theme: Theme,
1616
+ layout: MainWindowRenderLayout,
1617
+ frame?: number,
1618
+ foregroundDetachShortcut?: string,
1619
+ ): Component {
1592
1620
  const output = r.truncation?.text || getSingleResultOutput(r);
1593
1621
  const progress = r.progress || r.progressSummary;
1594
1622
  const isRunning = isResultRunning(r);
@@ -1613,7 +1641,7 @@ function renderSingleCompact(d: Details, r: Details["results"][number], theme: T
1613
1641
  for (const nestedLine of formatNestedWidgetLines(r.children, theme, width, false, progressSnapshotNow)) {
1614
1642
  c.addChild(new Text(truncLine(`${detailIndent}${nestedLine}`, width), 0, 0));
1615
1643
  }
1616
- c.addChild(new Text(truncLine(theme.fg("accent", `${detailIndent}${liveDetailHintText()}`), width), 0, 0));
1644
+ c.addChild(new Text(truncLine(theme.fg("accent", `${detailIndent}${foregroundSingleHintText(foregroundDetachShortcut)}`), width), 0, 0));
1617
1645
  if (r.artifactPaths) c.addChild(new Text(truncLine(theme.fg("dim", `${detailIndent}output: ${shortenPath(r.artifactPaths.outputPath)}`), width), 0, 0));
1618
1646
  return c;
1619
1647
  }
@@ -1635,7 +1663,7 @@ function renderSingleCompact(d: Details, r: Details["results"][number], theme: T
1635
1663
  function workflowRowGlyph(row: WorkflowChatProgressRow, theme: Theme, frame?: number): string {
1636
1664
  if (row.state === "running") return theme.fg("accent", runningGlyph(frame));
1637
1665
  if (row.state === "complete") return theme.fg("success", "✓");
1638
- if (row.state === "stopped") return theme.fg("warning", "■");
1666
+ if (row.state === "detached" || row.state === "stopped") return theme.fg("warning", "■");
1639
1667
  return theme.fg("error", "✗");
1640
1668
  }
1641
1669
 
@@ -1643,12 +1671,13 @@ function workflowRowStateLabel(row: WorkflowChatProgressRow, theme: Theme): stri
1643
1671
  const label = (row.state === "complete" ? "complete" : row.state).padEnd(8);
1644
1672
  if (row.state === "running") return theme.fg("accent", label);
1645
1673
  if (row.state === "complete") return theme.fg("success", label);
1646
- if (row.state === "stopped") return theme.fg("warning", label);
1674
+ if (row.state === "detached" || row.state === "stopped") return theme.fg("warning", label);
1647
1675
  return theme.fg("error", label);
1648
1676
  }
1649
1677
 
1650
- function workflowOverallState(rows: WorkflowChatProgressRow[], hasTerminalValue: boolean, isError?: boolean): "running" | "complete" | "failed" {
1678
+ function workflowOverallState(rows: WorkflowChatProgressRow[], hasTerminalValue: boolean, isError?: boolean): "running" | "complete" | "failed" | "paused" {
1651
1679
  if (isError || rows.some((row) => row.state === "failed")) return "failed";
1680
+ if (rows.some((row) => row.state === "detached")) return "paused";
1652
1681
  if ((rows.length > 0 && rows.every((row) => row.state === "complete")) || hasTerminalValue) return "complete";
1653
1682
  return "running";
1654
1683
  }
@@ -1657,7 +1686,7 @@ function renderWorkflowChatProgress(d: Details, result: AgentToolResult<Details>
1657
1686
  const workflow = d.workflow;
1658
1687
  const rows = workflow ? buildWorkflowChatProgressRows(workflow.trace) : [];
1659
1688
  const state = workflowOverallState(rows, workflow?.value !== undefined, result.isError);
1660
- const glyph = state === "running" ? theme.fg("accent", runningGlyph(frame)) : state === "complete" ? theme.fg("success", "✓") : theme.fg("error", "✗");
1689
+ const glyph = state === "running" ? theme.fg("accent", runningGlyph(frame)) : state === "complete" ? theme.fg("success", "✓") : state === "paused" ? theme.fg("warning", "■") : theme.fg("error", "✗");
1661
1690
  const width = getTermWidth() - 4;
1662
1691
  const runId = d.runId ? d.runId.slice(0, 12) : "workflow";
1663
1692
  const repoLabel = d.chatProgress?.repoLabel ?? (d.chatProgress?.repoRelation === "same" ? "same repo" : "other repo");
@@ -1678,7 +1707,7 @@ function renderWorkflowChatProgress(d: Details, result: AgentToolResult<Details>
1678
1707
  const label = row.label && row.label !== row.key ? ` ${oneLine(row.label)}` : "";
1679
1708
  const duration = row.durationMs !== undefined ? ` ${theme.fg("dim", `· ${formatDuration(row.durationMs)}`)}` : "";
1680
1709
  const run = row.runId ? ` ${theme.fg("dim", `[${row.runId.slice(0, 8)}]`)}` : "";
1681
- const error = row.error ? ` ${theme.fg("error", `· ${compactWorkflowError(row.error)}`)}` : "";
1710
+ const error = row.error ? ` ${theme.fg(row.state === "detached" ? "warning" : "error", `· ${compactWorkflowError(row.error)}`)}` : "";
1682
1711
  c.addChild(new Text(truncLine(`${rowIndent}${workflowRowGlyph(row, theme, frame)} ${status} ${theme.bold(row.key)}${label}${run}${duration}${error}`, width), 0, 0));
1683
1712
  }
1684
1713
  if (workflow?.emits.length) c.addChild(new Text(truncLine(theme.fg("dim", `${rowIndent}Emits ${workflow.emits.length}`), width), 0, 0));
@@ -1844,6 +1873,7 @@ export function renderSubagentResult(
1844
1873
  theme: Theme,
1845
1874
  frame?: number,
1846
1875
  rendererConfig?: MainWindowRendererConfig,
1876
+ foregroundDetachShortcut?: string,
1847
1877
  ): Component {
1848
1878
  const layout = resolveMainWindowRenderLayout(rendererConfig);
1849
1879
  const compact = (component: Component): Component => capCompactMainWindowResult(component, layout, theme, !options.expanded);
@@ -1877,8 +1907,9 @@ export function renderSubagentResult(
1877
1907
 
1878
1908
  if (d.mode === "single" && d.results.length === 1) {
1879
1909
  const r = d.results[0];
1910
+ const detachableShortcut = d.asyncId || d.background ? undefined : foregroundDetachShortcut;
1880
1911
  if (!r) return compact(renderMultiCompact(d, theme, layout, frame));
1881
- if (!expanded) return compact(renderSingleCompact(d, r, theme, layout, frame));
1912
+ if (!expanded) return compact(renderSingleCompact(d, r, theme, layout, frame, detachableShortcut));
1882
1913
  const isRunning = isResultRunning(r);
1883
1914
  const contextBadge = contextModeBadge(theme, r.context ?? d.context);
1884
1915
  const output = r.truncation?.text || getSingleResultOutput(r);
@@ -1918,7 +1949,7 @@ export function renderSubagentResult(
1918
1949
  if (liveStatusLine) {
1919
1950
  c.addChild(new Text(fit(theme.fg("accent", liveStatusLine)), 0, 0));
1920
1951
  }
1921
- c.addChild(new Text(fit(theme.fg("accent", liveDetailHintText())), 0, 0));
1952
+ c.addChild(new Text(fit(theme.fg("accent", foregroundSingleHintText(detachableShortcut))), 0, 0));
1922
1953
  if (r.artifactPaths) {
1923
1954
  c.addChild(new Text(fit(theme.fg("dim", `Artifacts: ${shortenPath(r.artifactPaths.outputPath)}`)), 0, 0));
1924
1955
  }
@@ -96,7 +96,7 @@ export function resolveWorkflowChatProgress(input: ResolveWorkflowChatProgressIn
96
96
 
97
97
  export interface WorkflowChatProgressRow {
98
98
  key: string;
99
- state: "running" | "complete" | "failed" | "stopped";
99
+ state: "running" | "complete" | "failed" | "detached" | "stopped";
100
100
  label?: string;
101
101
  phase?: string;
102
102
  runId?: string;
@@ -127,9 +127,11 @@ export function buildWorkflowChatProgressRows(trace: NonNullable<Details["workfl
127
127
  ? "complete"
128
128
  : entry.state === "failed"
129
129
  ? "failed"
130
- : entry.state === "stopped"
131
- ? "stopped"
132
- : "running";
130
+ : entry.state === "detached"
131
+ ? "detached"
132
+ : entry.state === "stopped"
133
+ ? "stopped"
134
+ : "running";
133
135
  const label = cleanLabel(entry.label);
134
136
  const phase = cleanLabel(entry.phase);
135
137
  if (label) next.label = label;