pi-better-background-tasks 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/src/shared-navigator.ts

@@ -918,7 +918,7 @@ function createOverlayComponent(
           width,
           deps.truncate,
           fg,
-          { minRows: detailRows, bottomFooter: false, logTailRows },
+          { minRows: detailRows, maxRows: detailRows, bottomFooter: false, logTailRows },
         );
       } else {
         transcriptDetail = null;
@@ -1003,21 +1003,33 @@ function buildTranscriptDetailLines(
   width: number,
   truncate: (s: string, width: number) => string,
   fg: (color: string, value: string) => string,
-  options: { minRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
+  options: { minRows?: number; maxRows?: number; bottomFooter?: boolean; logTailRows?: number } = {},
 ): string[] {
   const actions = [...(detail.footerActions ?? ["x close"]), "Esc close"].join(" · ");
   const tailRows = options.logTailRows ?? DEFAULT_LOG_TAIL_ROWS;
-  const shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
+  let shownTranscriptLines = transcriptLines.length ? transcriptLines.slice(-tailRows) : ["   (no transcript yet)"];
   const lines: string[] = [
     fg("accent", rule(detail.title, width)),
     dim(`   ← main · ${actions}`, fg),
     "",
     `   status   ${fg(toneColor(detail.statusTone, detail.status), detail.status)}`,
   ];
-  if (detail.subtitle) lines.push(`   summary  ${detail.subtitle}`);
-  for (const item of detail.metadata) lines.push(`   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`);
-  lines.push("", dim(section(`transcript · latest ${tailRows} rows`, width), fg));
-  if (detail.transcriptDiagnostic) lines.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  const optionalMetadata = [
+    ...(detail.subtitle ? [`   summary  ${detail.subtitle}`] : []),
+    ...detail.metadata.map((item) => `   ${item.label.padEnd(8, " ").slice(0, 8)} ${item.value}`),
+  ];
+  const transcriptHeader = ["", dim(section(`transcript · latest ${tailRows} rows`, width), fg)];
+  if (detail.transcriptDiagnostic) transcriptHeader.push(`   ${dim(detail.transcriptDiagnostic, fg)}`);
+  if (options.maxRows !== undefined) {
+    const fixedRows = lines.length + transcriptHeader.length + 1;
+    const transcriptBudget = Math.max(1, options.maxRows - fixedRows);
+    shownTranscriptLines = shownTranscriptLines.slice(-transcriptBudget);
+    const metadataBudget = Math.max(0, options.maxRows - fixedRows - shownTranscriptLines.length);
+    lines.push(...optionalMetadata.slice(0, metadataBudget));
+  } else {
+    lines.push(...optionalMetadata);
+  }
+  lines.push(...transcriptHeader);
   lines.push(...shownTranscriptLines);
   lines.push("");
   if (options.bottomFooter === false) return lines.map((line) => safeTruncate(line, width, truncate));

package/src/tools.ts

@@ -103,6 +103,12 @@ const StatusActionParams = Type.Object({
   verbose: Type.Optional(Type.Boolean()),
 });
 
+const BACKGROUND_ORCHESTRATION_GUIDELINES = [
+  "Use background tasks for genuinely long-running processes or repeated checks. Run short commands in the foreground.",
+  "When a structured plan is active, keep it as the coordinator ledger: launch relevant background work early, continue unblocked foreground work without polling, and update the plan after inspecting each terminal result or failure.",
+  "Do not treat launch as completion of the parent milestone; relevant background work must be terminal, inspected, and integrated before verification or completion.",
+];
+
 export function registerTools(pi: ExtensionAPI): void {
   let activeSession: BackgroundTaskCallbackOrigin | undefined;
   const getActiveSession = () => activeSession;
@@ -125,6 +131,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task_spawn",
     label: "BG Spawn",
     description: "Start a long-running background process and return immediately with its task id. For remote work, prefer structured ssh: pass ssh:{host,user} and put the remote command in command; spawn defaults to a remote tmux session with durable local logs and real remote stop. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. If tmux is missing, the preset attempts to install tmux non-interactively and fails closed with operator guidance when setup cannot proceed. Explicit remote.session=direct skips tmux, but direct mode has weaker stop semantics and may leave the remote process running. Never wait or poll in the foreground.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: SpawnParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
@@ -138,6 +145,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task_watch",
     label: "BG Watch",
     description: "Poll a command in the background until success_when, failure_when, or timeout matches. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command; each interval opens a direct one-shot SSH poll without tmux installation. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. Returns immediately with its task id. Default timeout 900 seconds; pass timeout_seconds:0 to disable.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: WatchParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       activeSession = getCallbackOrigin(ctx);
@@ -198,6 +206,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "bg_task",
     label: "BG Task",
     description: "Action wrapper for background tasks: spawn, watch, list, status, log, stop, or clear. For remote work, prefer structured ssh: pass ssh:{host,user} and provide the remote command in command. For short synchronous remote commands that should return output now, use remote_bash from pi-better-ssh. SSH spawn defaults to durable tmux; SSH watches use direct one-shot polls without tmux installation; remote.session=direct is a weaker-stop spawn escape hatch. Spawn/watch return immediately; do not poll in foreground. For action:status, default compact output and use verbose:true only for full metadata. For action:log, default compact tail and use tail_lines:0 only for explicit full logs.",
+    promptGuidelines: BACKGROUND_ORCHESTRATION_GUIDELINES,
     parameters: ActionParams,
     renderResult(result: unknown, options: unknown, theme: unknown) {
       return renderBackgroundTaskLogDisplay(result, options, theme);