@osolmaz/pi-workflows 0.8.1 → 0.9.0

package/src/extension/herdr-viewer.ts

@@ -0,0 +1,399 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { HERDR_PLUGIN_ENTRYPOINT, HERDR_PLUGIN_ID } from "../herdr/constants.js";
+export const PIW_SHORTCUT = "ctrl+shift+r";
+export const PIW_SHORTCUT_HINT = "Ctrl+Shift+R piw";
+
+const COMMAND_TIMEOUT_MS = 5_000;
+const MAX_JSON_CHARS = 1_000_000;
+const VIEWER_LABEL_PREFIX = "piw · ";
+
+export const VIEWER_PLACEMENTS = ["right", "below", "left", "above", "tab", "workspace"] as const;
+
+export type ViewerPlacement = (typeof VIEWER_PLACEMENTS)[number];
+
+export type WorkflowViewTarget = {
+  runId: string;
+  workflowName: string;
+  runDir: string;
+};
+
+export type HerdrCapability = { available: true } | { available: false; reason: string };
+
+export type ViewerOpenResult = {
+  paneId: string;
+  reused: boolean;
+  warning?: string;
+};
+
+type Exec = ExtensionAPI["exec"];
+
+type HerdrPane = {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+  label?: string;
+};
+
+type OpenedPane = {
+  paneId: string;
+  tabId: string;
+  workspaceId: string;
+};
+
+export class HerdrWorkflowViewer {
+  private readonly knownPanes = new Map<string, string>();
+  private readonly opening = new Map<string, Promise<ViewerOpenResult>>();
+
+  constructor(
+    private readonly exec: Exec,
+    private readonly env: NodeJS.ProcessEnv = process.env,
+  ) {}
+
+  async probe(): Promise<HerdrCapability> {
+    if (this.env.HERDR_ENV !== "1") {
+      return { available: false, reason: "Pi is not running in Herdr." };
+    }
+    try {
+      await this.currentPane();
+      const plugin = await this.runJson("herdr", [
+        "plugin",
+        "list",
+        "--plugin",
+        HERDR_PLUGIN_ID,
+        "--json",
+      ]);
+      if (!pluginIsEnabled(plugin)) {
+        return {
+          available: false,
+          reason: `Herdr plugin ${HERDR_PLUGIN_ID} is not linked and enabled.`,
+        };
+      }
+      await this.run("piw", ["--version"]);
+      return { available: true };
+    } catch (error) {
+      return { available: false, reason: errorMessage(error) };
+    }
+  }
+
+  async focusExisting(target: WorkflowViewTarget): Promise<boolean> {
+    return (await this.findAndFocus(target)) !== undefined;
+  }
+
+  async open(
+    target: WorkflowViewTarget,
+    placement: ViewerPlacement,
+    cwd: string,
+  ): Promise<ViewerOpenResult> {
+    const pending = this.opening.get(target.runId);
+    if (pending !== undefined) return await pending;
+
+    const opening = this.openOnce(target, placement, cwd).finally(() => {
+      if (this.opening.get(target.runId) === opening) this.opening.delete(target.runId);
+    });
+    this.opening.set(target.runId, opening);
+    return await opening;
+  }
+
+  private async openOnce(
+    target: WorkflowViewTarget,
+    placement: ViewerPlacement,
+    cwd: string,
+  ): Promise<ViewerOpenResult> {
+    const existingPaneId = await this.findAndFocus(target);
+    if (existingPaneId !== undefined) {
+      return { paneId: existingPaneId, reused: true };
+    }
+
+    const caller = await this.currentPane();
+    if (placement === "workspace") {
+      const opened = await this.openWorkspace(target, cwd);
+      this.knownPanes.set(target.runId, opened.paneId);
+      return { ...opened, reused: false };
+    }
+
+    const opened = await this.openPluginPane(target, placement, caller, cwd);
+    if (placement === "left" || placement === "above") {
+      try {
+        await this.run("herdr", [
+          "pane",
+          "swap",
+          "--source-pane",
+          opened.paneId,
+          "--target-pane",
+          caller.paneId,
+        ]);
+      } catch (error) {
+        await this.closePane(opened.paneId);
+        throw error;
+      }
+    }
+    this.knownPanes.set(target.runId, opened.paneId);
+    return { paneId: opened.paneId, reused: false };
+  }
+
+  private async findAndFocus(target: WorkflowViewTarget): Promise<string | undefined> {
+    const knownPaneId = this.knownPanes.get(target.runId);
+    if (knownPaneId !== undefined) {
+      try {
+        await this.run("herdr", ["plugin", "pane", "focus", knownPaneId]);
+        return knownPaneId;
+      } catch {
+        this.knownPanes.delete(target.runId);
+      }
+    }
+
+    const existing = await this.find(target);
+    if (existing === undefined) return undefined;
+    try {
+      await this.run("herdr", ["plugin", "pane", "focus", existing.paneId]);
+      this.knownPanes.set(target.runId, existing.paneId);
+      return existing.paneId;
+    } catch {
+      // The pane can close between the snapshot and focus request.
+      return undefined;
+    }
+  }
+
+  async find(target: WorkflowViewTarget): Promise<HerdrPane | undefined> {
+    const snapshot = await this.runJson("herdr", ["api", "snapshot"]);
+    return snapshotPanes(snapshot).find((pane) => pane.label === viewerPaneLabel(target.runId));
+  }
+
+  private async currentPane(): Promise<HerdrPane> {
+    return parseCurrentPane(await this.runJson("herdr", ["pane", "current", "--current"]));
+  }
+
+  private async openPluginPane(
+    target: WorkflowViewTarget,
+    placement: Exclude<ViewerPlacement, "workspace">,
+    caller: HerdrPane,
+    cwd: string,
+  ): Promise<OpenedPane> {
+    const args = [
+      "plugin",
+      "pane",
+      "open",
+      "--plugin",
+      HERDR_PLUGIN_ID,
+      "--entrypoint",
+      HERDR_PLUGIN_ENTRYPOINT,
+      "--cwd",
+      cwd,
+      "--env",
+      `PI_WORKFLOWS_RUN_ID=${target.runId}`,
+      "--env",
+      `PI_WORKFLOWS_RUN_DIR=${target.runDir}`,
+      "--focus",
+    ];
+    if (placement === "tab") {
+      args.push("--placement", "tab", "--workspace", caller.workspaceId);
+    } else {
+      args.push(
+        "--placement",
+        "split",
+        "--target-pane",
+        caller.paneId,
+        "--direction",
+        placement === "below" || placement === "above" ? "down" : "right",
+      );
+    }
+    return parseOpenedPane(await this.runJson("herdr", args));
+  }
+
+  private async openWorkspace(
+    target: WorkflowViewTarget,
+    cwd: string,
+  ): Promise<{ paneId: string; warning?: string }> {
+    const created = parseCreatedWorkspace(
+      await this.runJson("herdr", [
+        "workspace",
+        "create",
+        "--cwd",
+        cwd,
+        "--label",
+        workspaceLabel(target.workflowName),
+        "--no-focus",
+      ]),
+    );
+    let opened: OpenedPane;
+    try {
+      opened = parseOpenedPane(
+        await this.runJson("herdr", [
+          "plugin",
+          "pane",
+          "open",
+          "--plugin",
+          HERDR_PLUGIN_ID,
+          "--entrypoint",
+          HERDR_PLUGIN_ENTRYPOINT,
+          "--placement",
+          "tab",
+          "--workspace",
+          created.workspaceId,
+          "--cwd",
+          cwd,
+          "--env",
+          `PI_WORKFLOWS_RUN_ID=${target.runId}`,
+          "--env",
+          `PI_WORKFLOWS_RUN_DIR=${target.runDir}`,
+          "--focus",
+        ]),
+      );
+    } catch (error) {
+      await this.run("herdr", ["workspace", "close", created.workspaceId]).catch(() => undefined);
+      throw error;
+    }
+
+    try {
+      await this.run("herdr", ["tab", "close", created.bootstrapTabId]);
+      return { paneId: opened.paneId };
+    } catch (error) {
+      return {
+        paneId: opened.paneId,
+        warning: `The piw viewer opened, but its empty bootstrap tab could not be closed: ${errorMessage(error)}`,
+      };
+    }
+  }
+
+  private async closePane(paneId: string): Promise<void> {
+    await this.run("herdr", ["plugin", "pane", "close", paneId]).catch(() => undefined);
+  }
+
+  private async run(command: string, args: string[]): Promise<string> {
+    const result = await this.exec(command, args, { timeout: COMMAND_TIMEOUT_MS });
+    if (result.killed) {
+      throw new Error(`${command} timed out.`);
+    }
+    if (result.code !== 0) {
+      const message = result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`;
+      throw new Error(`${command} failed: ${boundedText(message)}`);
+    }
+    return result.stdout;
+  }
+
+  private async runJson(command: string, args: string[]): Promise<unknown> {
+    const stdout = await this.run(command, args);
+    if (stdout.length > MAX_JSON_CHARS) {
+      throw new Error(`${command} returned too much data.`);
+    }
+    try {
+      return JSON.parse(stdout) as unknown;
+    } catch {
+      throw new Error(`${command} returned invalid JSON.`);
+    }
+  }
+}
+
+export function parseViewerPlacement(value: string): ViewerPlacement | undefined {
+  return VIEWER_PLACEMENTS.find((placement) => placement === value);
+}
+
+export function viewerPaneLabel(runId: string): string {
+  return `${VIEWER_LABEL_PREFIX}${runId}`;
+}
+
+function pluginIsEnabled(value: unknown): boolean {
+  const result = recordValue(value, "result");
+  const plugins = result === undefined ? undefined : arrayValue(result, "plugins");
+  return (
+    plugins?.some(
+      (plugin) =>
+        recordValue(plugin, "plugin_id") === HERDR_PLUGIN_ID &&
+        recordValue(plugin, "enabled") === true,
+    ) === true
+  );
+}
+
+function parseCurrentPane(value: unknown): HerdrPane {
+  const result = requiredRecord(value, "result", "Herdr pane response");
+  return paneFromValue(requiredRecord(result, "pane", "Herdr pane response"));
+}
+
+function parseOpenedPane(value: unknown): OpenedPane {
+  const result = requiredRecord(value, "result", "Herdr plugin pane response");
+  const pluginPane = requiredRecord(result, "plugin_pane", "Herdr plugin pane response");
+  return paneFromValue(requiredRecord(pluginPane, "pane", "Herdr plugin pane response"));
+}
+
+function parseCreatedWorkspace(value: unknown): {
+  workspaceId: string;
+  bootstrapTabId: string;
+} {
+  const result = requiredRecord(value, "result", "Herdr workspace response");
+  const workspace = requiredRecord(result, "workspace", "Herdr workspace response");
+  const rootPane = requiredRecord(result, "root_pane", "Herdr workspace response");
+  return {
+    workspaceId: requiredString(workspace, "workspace_id", "Herdr workspace response"),
+    bootstrapTabId: requiredString(rootPane, "tab_id", "Herdr workspace response"),
+  };
+}
+
+function snapshotPanes(value: unknown): HerdrPane[] {
+  const result = requiredRecord(value, "result", "Herdr snapshot");
+  const snapshot = requiredRecord(result, "snapshot", "Herdr snapshot");
+  const panes = arrayValue(snapshot, "panes");
+  if (panes === undefined) throw new Error("Herdr snapshot has no panes.");
+  return panes.flatMap((pane) => {
+    try {
+      return [paneFromValue(pane)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+function paneFromValue(value: unknown): HerdrPane {
+  if (!isRecord(value)) throw new Error("Herdr returned an invalid pane.");
+  const label = recordValue(value, "label");
+  return {
+    paneId: requiredString(value, "pane_id", "Herdr pane"),
+    tabId: requiredString(value, "tab_id", "Herdr pane"),
+    workspaceId: requiredString(value, "workspace_id", "Herdr pane"),
+    ...(typeof label === "string" ? { label } : {}),
+  };
+}
+
+function workspaceLabel(workflowName: string): string {
+  const compact = workflowName.replace(/[\r\n\t]+/gu, " ").trim();
+  return `piw · ${(compact || "workflow").slice(0, 60)}`;
+}
+
+function requiredRecord(value: unknown, key: string, label: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`${label} is invalid.`);
+  const nested = value[key];
+  if (!isRecord(nested)) throw new Error(`${label} has no ${key}.`);
+  return nested;
+}
+
+function requiredString(value: Record<string, unknown>, key: string, label: string): string {
+  const nested = value[key];
+  if (typeof nested !== "string" || nested.length === 0) {
+    throw new Error(`${label} has no ${key}.`);
+  }
+  return nested;
+}
+
+function recordValue(value: unknown, key: string): unknown {
+  return isRecord(value) ? value[key] : undefined;
+}
+
+function arrayValue(value: unknown, key: string): unknown[] | undefined {
+  const nested = recordValue(value, key);
+  return Array.isArray(nested) ? nested : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function boundedText(value: string): string {
+  const compact = value
+    .replace(/[\r\n\t]+/gu, " ")
+    .replace(/ +/gu, " ")
+    .trim();
+  return compact.length <= 300 ? compact : `${compact.slice(0, 299)}…`;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/extension/index.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import path from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
@@ -37,6 +38,16 @@ import {
   type PiChildWorkflowStarter,
 } from "./controller-host.js";
 import { ConversationStepExecutor } from "./executor.js";
+import {
+  HerdrWorkflowViewer,
+  parseViewerPlacement,
+  PIW_SHORTCUT,
+  PIW_SHORTCUT_HINT,
+  VIEWER_PLACEMENTS,
+  type HerdrCapability,
+  type ViewerPlacement,
+  type WorkflowViewTarget,
+} from "./herdr-viewer.js";
 import { SessionRecorder } from "./recorder.js";
 import {
   registerWorkflowAgentStepMessageRenderer,
@@ -61,6 +72,18 @@ const MAX_WORKFLOW_LIST_ITEMS = 50;
 const MAX_WORKFLOW_LIST_NAME_CHARS = 3_500;
 const PRESENTATION_TIMEOUT_MS = 30_000;
 
+const PIW_PLACEMENT_LABELS: Readonly<Record<ViewerPlacement, string>> = {
+  right: "Split right",
+  below: "Split below",
+  left: "Split left",
+  above: "Split above",
+  tab: "New tab",
+  workspace: "New workspace",
+};
+const PIW_PLACEMENT_BY_LABEL = new Map(
+  VIEWER_PLACEMENTS.map((placement) => [PIW_PLACEMENT_LABELS[placement], placement] as const),
+);
+
 class PresentationSupersededError extends Error {}
 class PresentationTimeoutError extends Error {}
 
@@ -229,6 +252,17 @@ type WorkflowWidgetContent = string[] | WorkflowWidgetFactory;
 export default function piWorkflows(pi: ExtensionAPI) {
   registerWorkflowAgentStepMessageRenderer(pi);
 
+  const herdrEnabled = process.env.HERDR_ENV === "1";
+  const herdrViewer = new HerdrWorkflowViewer((command, args, options) =>
+    pi.exec(command, args, options),
+  );
+  let herdrCapability: HerdrCapability = {
+    available: false,
+    reason: "Herdr integration has not been checked.",
+  };
+  let workflowViewTarget: WorkflowViewTarget | null = null;
+  let herdrProbeGeneration = 0;
+
   // One runner identity per session; it names this session in run claims.
   const runnerId = randomUUID();
   let runQueueStore: SqliteControllerStore | null = null;
@@ -408,6 +442,12 @@ export default function piWorkflows(pi: ExtensionAPI) {
         width,
         theme,
         widgetSource.updateHistory,
+        ctx.mode === "tui" &&
+          herdrEnabled &&
+          herdrCapability.available &&
+          workflowViewTarget?.runId === widgetSource.state.runId
+          ? PIW_SHORTCUT_HINT
+          : undefined,
       );
       widgetShownScroll = view.scroll;
       widgetMaxScroll = view.maxScroll;
@@ -444,16 +484,76 @@ export default function piWorkflows(pi: ExtensionAPI) {
       snapshot,
       ...(updateHistory !== undefined ? { updateHistory: [...updateHistory] } : {}),
     };
+    workflowViewTarget = {
+      runId: state.runId,
+      workflowName: state.workflowName,
+      runDir: path.resolve(new WorkflowRunStore().runDirFor(state.runId)),
+    };
     renderWidget(ctx);
   };
 
   const clearWidget = (ctx: ExtensionContext) => {
     widgetSource = null;
+    workflowViewTarget = null;
     widgetScroll = null;
     setWidget(ctx, undefined);
     setStatus(ctx, undefined);
   };
 
+  const refreshHerdrCapability = async (ctx: ExtensionContext): Promise<HerdrCapability> => {
+    const generation = ++herdrProbeGeneration;
+    const capability = await herdrViewer.probe();
+    if (!sessionClosed && generation === herdrProbeGeneration) {
+      herdrCapability = capability;
+      renderWidget(ctx);
+    }
+    return capability;
+  };
+
+  const selectPiwPlacement = async (
+    ctx: ExtensionContext,
+  ): Promise<ViewerPlacement | undefined> => {
+    if (!ctx.hasUI || ctx.mode !== "tui") return undefined;
+    const label = await ctx.ui.select(
+      "Open workflow in piw",
+      VIEWER_PLACEMENTS.map((placement) => PIW_PLACEMENT_LABELS[placement]),
+    );
+    return label === undefined ? undefined : PIW_PLACEMENT_BY_LABEL.get(label);
+  };
+
+  const openPiw = async (
+    ctx: ExtensionContext,
+    requestedPlacement?: ViewerPlacement,
+  ): Promise<void> => {
+    const target = workflowViewTarget;
+    if (target === null) {
+      notify(ctx, "No workflow run is available to open in piw.", "warning");
+      return;
+    }
+    const capability = await refreshHerdrCapability(ctx);
+    if (!capability.available) {
+      notify(ctx, capability.reason, "warning");
+      return;
+    }
+    try {
+      if (await herdrViewer.focusExisting(target)) {
+        notify(ctx, `Focused the piw viewer for ${target.workflowName}.`);
+        return;
+      }
+      const placement = requestedPlacement ?? (await selectPiwPlacement(ctx));
+      if (placement === undefined) {
+        if (!ctx.hasUI || ctx.mode !== "tui") {
+          notify(ctx, "Specify a piw placement: right, below, left, above, tab, or workspace.");
+        }
+        return;
+      }
+      const opened = await herdrViewer.open(target, placement, ctx.cwd);
+      if (opened.warning !== undefined) notify(ctx, opened.warning, "warning");
+    } catch (error) {
+      notify(ctx, `Could not open piw: ${errorMessage(error)}`, "error");
+    }
+  };
+
   const scrollWidget = (ctx: ExtensionContext, delta: number) => {
     if (!widgetSource || widgetMaxScroll === 0) {
       return;
@@ -890,6 +990,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
       run.renewTimer.unref?.();
     }
     clearWidgetTimer();
+    workflowViewTarget = null;
     startWidgetTicker(ctx, run);
     if (!options.quiet) {
       notify(ctx, `Workflow ${workflow.name} started. Follow it live with: pi-workflows view`);
@@ -1462,6 +1563,25 @@ export default function piWorkflows(pi: ExtensionAPI) {
     }
   };
 
+  pi.registerCommand("piw", {
+    description: "Open the current workflow run in piw through Herdr",
+    getArgumentCompletions: async (prefix: string) => {
+      const items = VIEWER_PLACEMENTS.filter((placement) => placement.startsWith(prefix)).map(
+        (placement) => ({ value: placement, label: placement }),
+      );
+      return items.length > 0 ? items : null;
+    },
+    handler: async (args, ctx) => {
+      const value = args.trim();
+      const placement = value.length === 0 ? undefined : parseViewerPlacement(value);
+      if (value.length > 0 && placement === undefined) {
+        notify(ctx, "piw placement must be right, below, left, above, tab, or workspace.", "error");
+        return;
+      }
+      await openPiw(ctx, placement);
+    },
+  });
+
   pi.registerCommand("workflow", {
     description:
       "Run or manage a workflow: /workflow <name-or-path> [task | --input-json {…}]; also: status, pause, resume, cancel, answer",
@@ -1698,6 +1818,13 @@ export default function piWorkflows(pi: ExtensionAPI) {
     },
   });
 
+  if (herdrEnabled) {
+    pi.registerShortcut(PIW_SHORTCUT, {
+      description: "Open the current workflow run in piw",
+      handler: async (ctx) => await openPiw(ctx),
+    });
+  }
+
   pi.registerShortcut("shift+up", {
     description: "Scroll the workflow widget up",
     handler: (ctx) => scrollWidget(ctx, -WIDGET_SCROLL_STEP),
@@ -1711,6 +1838,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     sessionClosed = false;
     controllerContext = ctx;
+    if (herdrEnabled) void refreshHerdrCapability(ctx);
     try {
       const queue = ensureRunQueueStore(ctx.cwd);
       const migration = await migrateLegacyWorkflowSources({
@@ -1859,6 +1987,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
 
   pi.on("session_shutdown", async () => {
     sessionClosed = true;
+    herdrProbeGeneration += 1;
     systemTurnAbort = null;
     suppressWorkflowAssistantTail = false;
     supersedePresentation();
@@ -1889,6 +2018,7 @@ export default function piWorkflows(pi: ExtensionAPI) {
     clearWidgetTimer();
     stopWidgetTicker();
     widgetSource = null;
+    workflowViewTarget = null;
     widgetScroll = null;
   });
 }

package/src/extension/widget.ts

@@ -78,6 +78,7 @@ export function buildWidgetView(
   width = Number.POSITIVE_INFINITY,
   theme?: WidgetTheme,
   updateHistory?: WorkflowUpdateRecord[],
+  actionHint?: string,
 ): WidgetView {
   const availableWidth = Number.isFinite(width) ? Math.max(0, Math.floor(width)) : width;
   if (availableWidth === 0) return { lines: [], scroll: 0, maxScroll: 0 };
@@ -102,12 +103,18 @@ export function buildWidgetView(
       paint(theme, "warning", `  waiting on checkpoint: ${sanitizeText(state.waitingOn)}`),
     );
   }
-
+  const hint = actionHint?.trim() ? sanitizeText(actionHint) : undefined;
   const progress = progressLines(state, now, updateHistory).slice(0, 4);
-  const budget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
+  const baseBudget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
   const nodes = displayNodeIds(snapshot).map((nodeId) =>
     compactNodeLine(state, snapshot, nodeId, now, paused, theme),
   );
+  const combineHintWithWindow =
+    hint !== undefined && nodes.length > 0 && nodes.length + 1 > baseBudget;
+  if (hint !== undefined && !combineHintWithWindow) {
+    footer.push(paint(theme, "dim", `  ${hint}`));
+  }
+  const budget = PI_MAX_WIDGET_LINES - 1 - footer.length - progress.length;
   if (nodes.length === 0 || budget <= 0) {
     return {
       lines: fitLines(
@@ -120,7 +127,14 @@ export function buildWidgetView(
   }
 
   const anchor = scroll ?? compactFocusIndex(state, snapshot);
-  const windowed = windowLines(nodes, budget, anchor, scroll !== null, theme);
+  const windowed = windowLines(
+    nodes,
+    budget,
+    anchor,
+    scroll !== null,
+    theme,
+    combineHintWithWindow ? hint : undefined,
+  );
   const indentation = availableWidth >= 3 ? "  " : "";
   return {
     lines: fitLines(
@@ -356,8 +370,9 @@ function windowLines(
   anchor: number,
   anchorIsStart: boolean,
   theme?: WidgetTheme,
+  actionHint?: string,
 ): { lines: string[]; scroll: number; maxScroll: number } {
-  if (lines.length <= budget) {
+  if (lines.length <= budget && actionHint === undefined) {
     return { lines, scroll: 0, maxScroll: 0 };
   }
   const inner = Math.max(1, budget - 1);
@@ -369,7 +384,10 @@ function windowLines(
   const directions = [above > 0 ? `↑ ${above}` : "", below > 0 ? `↓ ${below}` : ""]
     .filter(Boolean)
     .join(" · ");
-  out.push(paint(theme, "dim", `${directions} more · shift+↑/↓ scroll`));
+  const controls = [`${directions} more`, "shift+↑/↓ scroll", actionHint]
+    .filter((item): item is string => Boolean(item))
+    .join(" · ");
+  out.push(paint(theme, "dim", controls));
   return { lines: out, scroll: start, maxScroll: Math.max(0, lines.length - inner) };
 }
 

package/src/herdr/constants.ts

@@ -0,0 +1,2 @@
+export const HERDR_PLUGIN_ID = "osolmaz.pi-workflows";
+export const HERDR_PLUGIN_ENTRYPOINT = "piw";