@maplezzk/pi-dynamic-workflows 1.0.0

package/src/extension.ts

@@ -0,0 +1,136 @@
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+import { Type } from "typebox";
+import { loadConfig, saveConfig } from "./config.ts";
+import { cancelRunningWorkflow, createWorkflowTool, renderWorkflowThemed } from "./index.ts";
+
+const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
+const LOG_PREFIX = "[pi-dynamic-workflows]";
+
+export default function extension(pi: ExtensionAPI) {
+  // Subagent session 不注册 workflow 工具：subagent 是 workflow 的执行节点，
+  // 不应再拥有启动 workflow 的能力（防止递归调用、误激活、误取消等）。
+  // pi-interactive-subagents 启动子 pi session 时会设置 PI_SUBAGENT_NAME。
+  if (process.env.PI_SUBAGENT_NAME) {
+    return;
+  }
+
+  const config = loadConfig();
+  const workflowTool = createWorkflowTool({ pi });
+  pi.registerTool(workflowTool);
+
+  // 异步模式：注册 workflow_cancel 工具
+  if (config.async) {
+    const cancelTool = defineTool({
+      name: "workflow_cancel",
+      label: "Cancel Workflow",
+      description: i18n.t("cancelToolDescription"),
+      promptSnippet: "Cancel a running background workflow.",
+      parameters: Type.Object({}),
+      async execute() {
+        const result = cancelRunningWorkflow();
+        if (result.cancelled) {
+          return {
+            content: [{ type: "text", text: i18n.t("cancelSent", { name: result.name }) }],
+            details: {},
+          };
+        }
+        return {
+          content: [{ type: "text", text: i18n.t("noneRunning") }],
+          details: {},
+        };
+      },
+      renderCall(_args, theme) {
+        return new Text(theme.fg("toolTitle", theme.bold("workflow_cancel")), 0, 0);
+      },
+    });
+    pi.registerTool(cancelTool);
+  }
+
+  // 注册异步模式的结果消息渲染器
+  pi.registerMessageRenderer("workflow_result", (message: any, _options: any, theme: any) => {
+    const snapshot = message.details;
+    if (!snapshot?.name) return undefined;
+
+    return {
+      render(width: number): string[] {
+        const hasError = snapshot.errorCount > 0;
+        const bgFn = hasError
+          ? (text: string) => theme.bg("toolErrorBg", text)
+          : (text: string) => theme.bg("toolSuccessBg", text);
+        const icon = hasError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+        const status = hasError ? "completed with errors" : "completed";
+        const elapsed = snapshot.durationMs ? `${Math.round(snapshot.durationMs / 1000)}s` : "?";
+
+        const header = `${icon} ${theme.fg("toolTitle", theme.bold(`Workflow: ${snapshot.name}`))} ${theme.fg("dim", "—")} ${status} ${theme.fg("dim", `(${elapsed})`)}`;
+
+        const contentLines = [header, ""];
+        const themed = renderWorkflowThemed(snapshot, theme, {
+          key: "workflow",
+          maxAgents: 4,
+          maxLogs: 1,
+          showResultPreviews: true,
+        });
+        contentLines.push(...themed.split("\n"));
+
+        const box = new Box(1, 1, bgFn);
+        box.addChild(new Text(contentLines.join("\n"), 0, 0));
+        return ["", ...box.render(width)];
+      },
+      invalidate(): void {},
+    };
+  });
+
+  registerConfigCommand(pi);
+
+  pi.on("session_start", () => {
+    const active = pi.getActiveTools();
+    const toolNames = [workflowTool.name];
+    if (loadConfig().async) toolNames.push("workflow_cancel");
+    for (const name of toolNames) {
+      if (!active.includes(name)) {
+        pi.setActiveTools([...pi.getActiveTools(), name]);
+      }
+    }
+  });
+
+  // 会话关闭时取消运行中的异步 workflow
+  pi.on("session_shutdown", () => {
+    cancelRunningWorkflow();
+  });
+}
+
+/** /workflow-config 交互式配置命令：切换执行后端与异步模式，持久化到 JSON。 */
+function registerConfigCommand(pi: ExtensionAPI) {
+  pi.registerCommand("workflow-config", {
+    description: i18n.t("commandDescription"),
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) return;
+      while (true) {
+        const cfg = loadConfig();
+        const EXIT = i18n.t("exit");
+        const on = i18n.t("on");
+        const off = i18n.t("off");
+        const choices = [
+          i18n.t("toggleBackend", { value: cfg.backend }),
+          i18n.t("toggleAsync", { value: cfg.async ? on : off }),
+          EXIT,
+        ];
+        const choice = await ctx.ui.select(i18n.t("configTitle"), choices);
+        if (choice === undefined || choice === EXIT) return;
+
+        if (choice === choices[0]) {
+          const saved = saveConfig({ backend: cfg.backend === "subagent" ? "workflow" : "subagent" });
+          ctx.ui.notify(`${LOG_PREFIX} ${i18n.t("savedBackend", { value: saved.backend })}`, "info");
+        } else if (choice === choices[1]) {
+          const saved = saveConfig({ async: !cfg.async });
+          ctx.ui.notify(
+            `${LOG_PREFIX} ${i18n.t("savedAsync", { value: saved.async ? on : off })} ${i18n.t("reloadHint")}`,
+            "info",
+          );
+        }
+      }
+    },
+  });
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export type { AgentRunOptions, AgentRunResult, WorkflowAgentOptions } from "./agent.ts";
+export { WorkflowAgent } from "./agent.ts";
+export type {
+  WorkflowAgentSnapshot,
+  WorkflowAgentStatus,
+  WorkflowDisplay,
+  WorkflowDisplayOptions,
+  WorkflowSnapshot,
+  WorkflowTheme,
+} from "./display.ts";
+export {
+  createToolUpdateWorkflowDisplay,
+  createWidgetWorkflowDisplay,
+  createWorkflowSnapshot,
+  preview,
+  recomputeWorkflowSnapshot,
+  renderWorkflowLines,
+  renderWorkflowText,
+  renderWorkflowThemed,
+  renderWorkflowWidgetLines,
+} from "./display.ts";
+export type { StructuredOutputCapture, StructuredOutputToolOptions } from "./structured-output.ts";
+export { createStructuredOutputTool } from "./structured-output.ts";
+export type { SubagentWorkflowAgentOptions } from "./subagent-agent.ts";
+export { SubagentWorkflowAgent } from "./subagent-agent.ts";
+export type {
+  AgentOptions,
+  WorkflowMeta,
+  WorkflowMetaPhase,
+  WorkflowRunOptions,
+  WorkflowRunResult,
+} from "./workflow.ts";
+export { parseWorkflowScript, runWorkflow } from "./workflow.ts";
+export type { WorkflowToolInput, WorkflowToolOptions } from "./workflow-tool.ts";
+export { cancelRunningWorkflow, createWorkflowTool } from "./workflow-tool.ts";
+export type { WorkflowBackend, WorkflowConfig } from "./config.ts";
+export { configPath, loadConfig, saveConfig } from "./config.ts";

package/src/structured-output.ts

@@ -0,0 +1,47 @@
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+
+export interface StructuredOutputCapture<T = unknown> {
+  value: T | undefined;
+  called: boolean;
+}
+
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+  schema: TSchemaDef;
+  capture: StructuredOutputCapture<Static<TSchemaDef>>;
+  name?: string;
+}
+
+/**
+ * Create a terminating tool that captures validated params as the subagent result.
+ *
+ * Pi validates `params` against `schema` before execute() is called. Returning
+ * `terminate: true` lets the subagent finish on this tool call without paying for
+ * an extra assistant follow-up turn.
+ */
+export function createStructuredOutputTool<TSchemaDef extends TSchema>({
+  schema,
+  capture,
+  name = "structured_output",
+}: StructuredOutputToolOptions<TSchemaDef>): ToolDefinition<TSchemaDef, Static<TSchemaDef>> {
+  return defineTool({
+    name,
+    label: "Structured Output",
+    description: "Return the final machine-readable result for this subagent task.",
+    promptSnippet: "Return final machine-readable output",
+    promptGuidelines: [
+      `${name} is the final answer channel for this task; call ${name} exactly once when done.`,
+      `Do not write a prose final answer after calling ${name}.`,
+    ],
+    parameters: schema,
+    async execute(_toolCallId, params) {
+      capture.value = params;
+      capture.called = true;
+      return {
+        content: [{ type: "text", text: "Structured output received." }],
+        details: params,
+        terminate: true,
+      };
+    },
+  });
+}

package/src/subagent-agent.ts

@@ -0,0 +1,206 @@
+/**
+ * SubagentWorkflowAgent — workflow backend backed by pi-interactive-subagents.
+ *
+ * Activated when PI_WORKFLOW_BACKEND=subagent.  Uses launchSubagent / watchSubagent
+ * to run each agent() call as a separate tmux-pane subagent with real tool access.
+ * Structured output is enforced via the subagent's structured_output tool (ajv validation)
+ * rather than the in-memory session's structured_output mechanism.
+ */
+
+// ── defensive .jsonl validator ──
+// 拦截 pollForExit 误判（fast path 命中残留 .exit 或 slow path 读到 stale
+// sentinel）导致的"子 agent 根本没启动就被判定完成"。herdr-split.log 9:01 失败批次
+// 模式：pane run 6ms 后 close，subagentSessionFile.jsonl 永远不存在。
+import { existsSync, statSync } from "node:fs";
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));
+
+/** 校验子 agent 的 .jsonl 会话文件是否真实存在且非空，防止 pollForExit 误判。 */
+function sessionFileLooksValid(jsonlPath: string): { ok: boolean; reason: string; size: number } {
+  if (!existsSync(jsonlPath)) return { ok: false, reason: "missing", size: 0 };
+  try {
+    const size = statSync(jsonlPath).size;
+    if (size === 0) return { ok: false, reason: "empty", size: 0 };
+    return { ok: true, reason: "ok", size };
+  } catch (e: unknown) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, reason: `stat_failed:${msg}`, size: 0 };
+  }
+}
+
+// ── types lifted from pi-interactive-subagents ──
+interface SubagentCtx {
+  sessionManager: {
+    getSessionFile(): string | null;
+    getSessionId(): string;
+    getSessionDir(): string;
+  };
+  cwd: string;
+  model?: unknown;
+  modelRegistry?: unknown;
+  ui?: { notify?(message: string, level: "info" | "warning" | "error"): void };
+  [key: string]: unknown;
+}
+
+/** Mirror of pi-interactive-subagents' RunningSubagent (subset we care about). */
+interface RunningSubagent {
+  id: string;
+  name: string;
+  surface: string;
+  sessionFile: string;
+  startTime: number;
+}
+
+/** Mirror of pi-interactive-subagents' SubagentResult. */
+interface SubagentResult {
+  name: string;
+  task: string;
+  summary: string;
+  sessionFile?: string;
+  exitCode: number;
+  elapsed: number;
+  structuredOutput?: unknown;
+}
+
+// ── subagent API (lazily resolved from globalThis) ──
+interface SubagentApi {
+  launchSubagent(
+    params: Record<string, unknown>,
+    ctx: SubagentCtx,
+    options?: { surface?: string },
+  ): Promise<RunningSubagent>;
+  watchSubagent(running: RunningSubagent, signal: AbortSignal): Promise<SubagentResult>;
+}
+
+function getSubagentApi(): SubagentApi {
+  const api = (globalThis as any).__pi_subagents;
+  if (!api) {
+    throw new Error(i18n.t("subagentRequired"));
+  }
+  return api as SubagentApi;
+}
+
+// ── options ──
+export interface SubagentWorkflowAgentOptions {
+  cwd?: string;
+  /** Pi extension context (passed from workflow-tool execute callback). */
+  launchCtx: SubagentCtx;
+  /** Model override for subagent sessions (string id, not Model object). */
+  model?: string;
+  /** Extra instructions prepended to every agent() prompt. */
+  instructions?: string;
+}
+
+export interface AgentRunOptions {
+  label?: string;
+  schema?: unknown;
+  signal?: AbortSignal;
+  instructions?: string;
+  /** 覆盖 subagent 的模型，不传则走默认 fallback */
+  model?: string;
+}
+
+export type AgentRunResult = unknown;
+
+// ── agent ──
+export class SubagentWorkflowAgent {
+  private readonly cwd: string;
+  private readonly launchCtx: SubagentCtx;
+  private readonly model?: string;
+  private readonly instructions?: string;
+
+  constructor(options: SubagentWorkflowAgentOptions) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.launchCtx = options.launchCtx;
+    this.model = options.model;
+    this.instructions = options.instructions;
+  }
+
+  async run(prompt: string, options: AgentRunOptions = {}): Promise<AgentRunResult> {
+    const api = getSubagentApi();
+
+    const taskParts = [
+      this.instructions,
+      options.instructions,
+      options.label ? `Task label: ${options.label}` : undefined,
+      prompt,
+    ].filter(Boolean);
+    const task = taskParts.join("\n\n");
+
+    const launchedAt = Date.now();
+    const running = await api.launchSubagent(
+      {
+        name: options.label ?? "workflow-agent",
+        task,
+        model: options.model ?? this.model,
+        cwd: this.cwd,
+        ...(options.schema ? { structuredOutputSchema: options.schema } : {}),
+      },
+      this.launchCtx,
+    );
+    this.launchCtx.ui?.notify?.(`[workflow] "${options.label ?? "workflow-agent"}" launched (${Date.now() - launchedAt}ms)`, "info");
+
+    // Create abort signal that combines caller's signal with module-level abort
+    const abortController = new AbortController();
+    let removeAbort: (() => void) | undefined;
+    if (options.signal) {
+      if (options.signal.aborted) {
+        throw new Error("Subagent was aborted");
+      }
+      const onAbort = () => abortController.abort();
+      options.signal.addEventListener("abort", onAbort, { once: true });
+      removeAbort = () => options.signal?.removeEventListener("abort", onAbort);
+    }
+
+    try {
+      const watchStartedAt = Date.now();
+      const result = await api.watchSubagent(running, abortController.signal);
+      const watchTookMs = Date.now() - watchStartedAt;
+      this.launchCtx.ui?.notify?.(
+        `[workflow] "${options.label ?? "workflow-agent"}" done (${watchTookMs}ms) → ` +
+          `exitCode=${result.exitCode} hasOutput=${result.structuredOutput !== undefined}`,
+        "info",
+      );
+
+      if (options.signal?.aborted) throw new Error("Subagent was aborted");
+
+      // 防御性校验：pollForExit 任何 reason (done / structured_output / ping / sentinel)
+      // 都要求 .jsonl 实际存在 + 非空。如果 .jsonl 不存在/为空，说明子 pi 根本没启动
+      // （典型场景：pane run 6ms 内 close、herdr 静默失败、stale .exit 残留命中 fast path）。
+      // 这种"假成功"比"明确失败"更危险——workflow 会把空数据当成结果继续往下走。
+      const jsonlCheck = sessionFileLooksValid(running.sessionFile);
+      if (!jsonlCheck.ok) {
+        this.launchCtx.ui?.notify?.(
+          `[workflow] "${options.label ?? "workflow-agent"}" SESSION FILE ${jsonlCheck.reason} ` +
+            `(${watchTookMs}ms, session ${running.sessionFile}) — ` +
+            `subagent never actually started, likely pollForExit false positive`,
+          "error",
+        );
+        throw new Error(
+          `Subagent pollForExit returned in ${watchTookMs}ms but session file is ` +
+            `${jsonlCheck.reason} (${running.sessionFile}). ` +
+            `This indicates the subagent never actually started — ` +
+            `likely a false positive from pollForExit (herdr workspace state issue). ` +
+            `Try restarting the herdr workspace or check for stale .exit sidecar files.`,
+        );
+      }
+
+      if (options.schema) {
+        if (result.structuredOutput === undefined) {
+          this.launchCtx.ui?.notify?.(
+            `[workflow] "${options.label ?? "workflow-agent"}" ${watchTookMs}ms exitCode=${result.exitCode} ` +
+              `— finished without calling structured_output`,
+            "warning",
+          );
+          throw new Error("Subagent finished without calling structured_output");
+        }
+        return result.structuredOutput as AgentRunResult;
+      }
+
+      return result.summary as AgentRunResult;
+    } finally {
+      removeAbort?.();
+    }
+  }
+}