@osolmaz/pi-workflows 0.8.2 → 0.9.0

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";

package/src/herdr/setup.ts

@@ -0,0 +1,93 @@
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { HERDR_PLUGIN_ID } from "./constants.js";
+
+export type HerdrSetupResult = {
+  changed: boolean;
+  message: string;
+};
+
+type Spawn = (command: string, args: readonly string[]) => SpawnSyncReturns<string>;
+
+export function setupHerdrPlugin(packageRoot: string, spawn: Spawn = runCommand): HerdrSetupResult {
+  const root = path.resolve(packageRoot);
+  const manifest = path.join(root, "herdr-plugin.toml");
+  if (!fs.existsSync(manifest)) {
+    throw new Error(`Herdr plugin manifest not found: ${manifest}`);
+  }
+
+  const listed = spawn("herdr", ["plugin", "list", "--plugin", HERDR_PLUGIN_ID, "--json"]);
+  if (listed.error) throw new Error(`Could not run Herdr: ${listed.error.message}`);
+  if (listed.status !== 0) {
+    throw new Error(`Could not inspect Herdr plugins: ${bounded(listed.stderr || listed.stdout)}`);
+  }
+  const installed = installedPlugin(listed.stdout);
+  if (installed !== undefined) {
+    if (path.resolve(installed.root) !== root) {
+      throw new Error(
+        `Herdr plugin ${HERDR_PLUGIN_ID} is already registered from ${installed.root}. Unlink it before linking ${root}.`,
+      );
+    }
+    if (installed.enabled) {
+      return { changed: false, message: `Herdr plugin ${HERDR_PLUGIN_ID} is already linked.` };
+    }
+    const enabled = spawn("herdr", ["plugin", "enable", HERDR_PLUGIN_ID]);
+    if (enabled.error) throw new Error(`Could not run Herdr: ${enabled.error.message}`);
+    if (enabled.status !== 0) {
+      throw new Error(
+        `Could not enable the Herdr plugin: ${bounded(enabled.stderr || enabled.stdout)}`,
+      );
+    }
+    return { changed: true, message: `Enabled Herdr plugin ${HERDR_PLUGIN_ID}.` };
+  }
+
+  const linked = spawn("herdr", ["plugin", "link", root]);
+  if (linked.error) throw new Error(`Could not run Herdr: ${linked.error.message}`);
+  if (linked.status !== 0) {
+    throw new Error(`Could not link the Herdr plugin: ${bounded(linked.stderr || linked.stdout)}`);
+  }
+  return { changed: true, message: `Linked Herdr plugin ${HERDR_PLUGIN_ID} from ${root}.` };
+}
+
+function installedPlugin(stdout: string): { root: string; enabled: boolean } | undefined {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout) as unknown;
+  } catch {
+    throw new Error("Herdr returned invalid plugin JSON.");
+  }
+  if (!isRecord(value) || !isRecord(value.result) || !Array.isArray(value.result.plugins)) {
+    throw new Error("Herdr returned an invalid plugin list.");
+  }
+  for (const plugin of value.result.plugins) {
+    if (
+      isRecord(plugin) &&
+      plugin.plugin_id === HERDR_PLUGIN_ID &&
+      typeof plugin.plugin_root === "string" &&
+      typeof plugin.enabled === "boolean"
+    ) {
+      return { root: plugin.plugin_root, enabled: plugin.enabled };
+    }
+  }
+  return undefined;
+}
+
+function runCommand(command: string, args: readonly string[]): SpawnSyncReturns<string> {
+  return spawnSync(command, [...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+function bounded(value: string): string {
+  const compact = value
+    .replace(/[\r\n\t]+/gu, " ")
+    .replace(/ +/gu, " ")
+    .trim();
+  return compact.length <= 300 ? compact : `${compact.slice(0, 299)}…`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/viewer/cli.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import fs, { realpathSync } from "node:fs";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { SqliteControllerStore } from "../controllers/sqlite.js";
 import { projectControllerStoreBaseDir } from "../controllers/store.js";
+import { setupHerdrPlugin } from "../herdr/setup.js";
 import { sanitizeText } from "../render/ansi.js";
 import { listRunBundles, readRunBundle, workflowRunsBaseDir } from "../workflows/store.js";
 import {
@@ -23,6 +24,7 @@ Usage:
   pi-workflows controllers [--controller-dir <dir>]
   pi-workflows controller <controller> <key> [--controller-dir <dir>]
   pi-workflows host [--project <dir>] [-- <extra pi args>]
+  pi-workflows herdr setup
 
 Commands:
   view          Open the live workflow TUI. With --once, print a snapshot.
@@ -30,6 +32,7 @@ Commands:
   controllers   List durable controller resources.
   controller    Show one resource, its effects, child workflows, and events.
   host          Run the always-on workflow host in the foreground.
+  herdr         Set up the bundled Herdr plugin.
 
 Options:
   --dir <runsDir>          Runs directory (default: ~/.pi/agent/workflows/runs)
@@ -43,6 +46,7 @@ export type CliArgs = {
   runId?: string;
   controllerName?: string;
   resourceKey?: string;
+  herdrAction?: string;
   dir: string;
   controllerDir: string;
   once: boolean;
@@ -98,6 +102,12 @@ export function parseCliArgs(argv: string[]): CliArgs {
       once,
     };
   }
+  if (command === "herdr") {
+    if (positionals.length !== 1 || positionals[0] !== "setup") {
+      throw new Error("herdr requires the setup action");
+    }
+    return { command, herdrAction: positionals[0], dir, controllerDir, once };
+  }
   if (positionals.length > 1) {
     throw new Error(`Unexpected argument: ${positionals[1]}`);
   }
@@ -229,6 +239,11 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
     if (args.command === "host") {
       return await runHost(args.project ?? process.cwd(), args.piArgs);
     }
+    if (args.command === "herdr") {
+      const result = setupHerdrPlugin(packageRoot());
+      process.stdout.write(`${result.message}\n`);
+      return 0;
+    }
     if (args.command === "view") {
       if (args.once || !process.stdout.isTTY) {
         await printOnce(args.dir, args.runId);
@@ -271,6 +286,10 @@ function openControllerStore(controllerDir: string): SqliteControllerStore | und
   return new SqliteControllerStore(file, { readOnly: true });
 }
 
+function packageRoot(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+}
+
 function requiredValue(args: string[], option: string): string {
   const value = args.shift();
   if (!value) {