@maplezzk/pi-dynamic-workflows 1.0.0

package/README.md

@@ -0,0 +1,58 @@
+# pi-dynamic-workflows
+
+Claude-Code-style dynamic workflow orchestration for Pi.
+
+> **Fork notice:** This package is a fork of [michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows) (MIT license). Full credit to the original author **michaelliv** for the design and implementation. Changes in this fork: monorepo integration, i18n support, and config migration from environment variables to a slash command.
+
+## Features
+
+- Define multi-agent workflows as plain JavaScript scripts with `meta`, `phase()`, `agent()`, `parallel()`, and `pipeline()` primitives
+- Static validation of workflow scripts via acorn AST parsing
+- Optional subagent backend via `pi-interactive-subagents` for real tool access per agent
+- Async background execution mode with live status widget
+- Configurable via `/workflow-config` slash command (persisted to JSON)
+
+## Installation
+
+```bash
+pi install @maplezzk/pi-dynamic-workflows
+```
+
+## Configuration
+
+Run `/workflow-config` to interactively configure:
+
+- **Execution backend**: `workflow` (built-in in-process agent) or `subagent` (requires `pi-interactive-subagents`)
+- **Async mode**: run workflows in the background with a live status widget
+
+Config is persisted to `~/.pi/agent/extensions/pi-dynamic-workflows/config.json`.
+
+Environment variables are supported as fallback only:
+
+| Variable | Values | Effect |
+|---|---|---|
+| `PI_WORKFLOW_BACKEND` | `subagent` | Use subagent backend (fallback) |
+| `PI_WORKFLOW_ASYNC` | `true` | Enable async mode (fallback) |
+
+JSON config takes priority over environment variables.
+
+## Usage
+
+```js
+// In a workflow script passed to the workflow tool:
+export const meta = {
+  name: 'my_workflow',
+  description: 'Does something useful',
+  phases: [{ title: 'Phase 1' }]
+};
+
+phase('Phase 1');
+const result = await agent('Analyze the codebase', {
+  label: 'code analysis',
+  schema: { type: 'object', properties: { summary: { type: 'string' } }, required: ['summary'] }
+});
+```
+
+## License
+
+MIT — see original repository for details.

package/README.zh-CN.md

@@ -0,0 +1,58 @@
+# pi-dynamic-workflows
+
+为 Pi 提供 Claude-Code 风格的动态 workflow 编排能力。
+
+> **Fork 说明：** 本包 fork 自 [michaelliv/pi-dynamic-workflows](https://github.com/Michaelliv/pi-dynamic-workflows)（MIT 协议）。设计与实现的版权归原作者 **michaelliv** 所有。本 fork 的变更：monorepo 集成、i18n 支持、配置方式从环境变量迁移为斜杠命令。
+
+## 功能
+
+- 用纯 JavaScript 脚本定义多 agent 工作流，支持 `meta`、`phase()`、`agent()`、`parallel()`、`pipeline()` 原语
+- 通过 acorn AST 解析对 workflow 脚本进行静态校验
+- 可选 subagent 后端（依赖 `pi-interactive-subagents`），每个 agent 拥有真实工具访问
+- 异步后台执行模式，带实时状态 widget
+- 通过 `/workflow-config` 斜杠命令配置（持久化到 JSON）
+
+## 安装
+
+```bash
+pi install @maplezzk/pi-dynamic-workflows
+```
+
+## 配置
+
+运行 `/workflow-config` 进行交互式配置：
+
+- **执行后端**：`workflow`（内置进程内 agent）或 `subagent`（需安装 `pi-interactive-subagents`）
+- **异步模式**：后台运行 workflow，带实时状态 widget
+
+配置持久化到 `~/.pi/agent/extensions/pi-dynamic-workflows/config.json`。
+
+环境变量仅作兜底支持：
+
+| 变量 | 值 | 效果 |
+|---|---|---|
+| `PI_WORKFLOW_BACKEND` | `subagent` | 使用 subagent 后端（兜底） |
+| `PI_WORKFLOW_ASYNC` | `true` | 启用异步模式（兜底） |
+
+JSON 配置优先级高于环境变量。
+
+## 用法
+
+```js
+// 传给 workflow 工具的脚本：
+export const meta = {
+  name: 'my_workflow',
+  description: '完成某件有用的事',
+  phases: [{ title: '阶段 1' }]
+};
+
+phase('阶段 1');
+const result = await agent('分析代码库', {
+  label: '代码分析',
+  schema: { type: 'object', properties: { summary: { type: 'string' } }, required: ['summary'] }
+});
+```
+
+## 许可证
+
+MIT — 详见原始仓库。

package/index.ts

@@ -0,0 +1,2 @@
+export { default } from "./src/extension.ts";
+export * from "./src/index.ts";

package/locales/index.json

@@ -0,0 +1,78 @@
+{
+  "commandDescription": {
+    "zh-CN": "配置 workflow 执行后端与异步模式",
+    "en-US": "Configure workflow execution backend and async mode"
+  },
+  "configTitle": {
+    "zh-CN": "Workflow 配置",
+    "en-US": "Workflow Config"
+  },
+  "exit": {
+    "zh-CN": "退出",
+    "en-US": "Exit"
+  },
+  "on": {
+    "zh-CN": "开启",
+    "en-US": "on"
+  },
+  "off": {
+    "zh-CN": "关闭",
+    "en-US": "off"
+  },
+  "toggleBackend": {
+    "zh-CN": "切换执行后端（当前：{value}）",
+    "en-US": "Toggle execution backend (current: {value})"
+  },
+  "toggleAsync": {
+    "zh-CN": "切换异步模式（当前：{value}）",
+    "en-US": "Toggle async mode (current: {value})"
+  },
+  "savedBackend": {
+    "zh-CN": "执行后端已切换为：{value}",
+    "en-US": "Execution backend switched to: {value}"
+  },
+  "savedAsync": {
+    "zh-CN": "异步模式已切换为：{value}",
+    "en-US": "Async mode switched to: {value}"
+  },
+  "reloadHint": {
+    "zh-CN": "需 /reload 生效",
+    "en-US": "Requires /reload to take effect"
+  },
+  "cancelToolDescription": {
+    "zh-CN": "取消正在后台运行的 workflow",
+    "en-US": "Cancel a running background workflow"
+  },
+  "cancelSent": {
+    "zh-CN": "Workflow {name} 取消请求已发送",
+    "en-US": "Cancel request sent for Workflow {name}"
+  },
+  "noneRunning": {
+    "zh-CN": "当前没有正在运行的 workflow",
+    "en-US": "No workflow is currently running"
+  },
+  "alreadyRunning": {
+    "zh-CN": "已有 workflow 在运行: {name}",
+    "en-US": "A workflow is already running: {name}"
+  },
+  "resultWritten": {
+    "zh-CN": "Workflow {name} 已完成（{count} 个 agent，耗时 {ms}ms）。\n结果已写入: {path}",
+    "en-US": "Workflow {name} completed with {count} agent(s) in {ms}ms.\nResult written to: {path}"
+  },
+  "cancelled": {
+    "zh-CN": "Workflow {name} 已取消",
+    "en-US": "Workflow {name} cancelled"
+  },
+  "started": {
+    "zh-CN": "Workflow {name} 已启动，后台执行中...",
+    "en-US": "Workflow {name} started, running in background..."
+  },
+  "totalResult": {
+    "zh-CN": "📄 总结果：{path}",
+    "en-US": "📄 Result: {path}"
+  },
+  "subagentRequired": {
+    "zh-CN": "PI_WORKFLOW_BACKEND=subagent 需要 pi-interactive-subagents 扩展。\n安装: pi install pi-interactive-subagents",
+    "en-US": "PI_WORKFLOW_BACKEND=subagent requires the pi-interactive-subagents extension.\nInstall: pi install pi-interactive-subagents"
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@maplezzk/pi-dynamic-workflows",
+  "version": "1.0.0",
+  "description": "Claude-Code-style dynamic workflow orchestration for Pi. Fork of michaelliv/pi-dynamic-workflows.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "types",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "michaelliv",
+  "contributors": [
+    "maplezzk"
+  ],
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-dynamic-workflows",
+  "bugs": "https://github.com/maplezzk/pi-extensions/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-dynamic-workflows"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "workflow",
+    "agents"
+  ],
+  "dependencies": {
+    "acorn": "^8.16.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0",
+    "@earendil-works/pi-tui": ">=0.80.0 <0.81.0",
+    "pi-extensions-i18n": "^0.3.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@earendil-works/pi-tui": "0.80.10",
+    "@types/node": "24.12.4",
+    "pi-extensions-i18n": "^0.3.0",
+    "tsx": "4.23.1",
+    "typebox": "latest",
+    "typescript": "5.9.3"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,131 @@
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import {
+  type CreateAgentSessionOptions,
+  createAgentSession,
+  createCodingTools,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+import { createStructuredOutputTool, type StructuredOutputCapture } from "./structured-output.ts";
+
+export interface WorkflowAgentOptions {
+  cwd?: string;
+  /** Extra tools available to the subagent in addition to the structured output tool. */
+  tools?: ToolDefinition[];
+  /** Override any createAgentSession option (model, authStorage, resourceLoader, etc.). */
+  session?: Partial<CreateAgentSessionOptions>;
+  /** Extra system guidance prepended to every subagent task. */
+  instructions?: string;
+}
+
+export interface AgentRunOptions<TSchemaDef extends TSchema | undefined = undefined> {
+  label?: string;
+  schema?: TSchemaDef;
+  tools?: ToolDefinition[];
+  instructions?: string;
+  signal?: AbortSignal;
+}
+
+export type AgentRunResult<TSchemaDef extends TSchema | undefined> = TSchemaDef extends TSchema
+  ? Static<TSchemaDef>
+  : string;
+
+export class WorkflowAgent {
+  private readonly cwd: string;
+  private readonly baseTools: ToolDefinition[];
+  private readonly sessionOptions: Partial<CreateAgentSessionOptions>;
+  private readonly instructions?: string;
+
+  constructor(options: WorkflowAgentOptions = {}) {
+    this.cwd = options.cwd ?? process.cwd();
+    this.baseTools = options.tools ?? createCodingTools(this.cwd);
+    this.sessionOptions = options.session ?? {};
+    this.instructions = options.instructions;
+  }
+
+  async run<TSchemaDef extends TSchema | undefined = undefined>(
+    prompt: string,
+    options: AgentRunOptions<TSchemaDef> = {},
+  ): Promise<AgentRunResult<TSchemaDef>> {
+    const capture: StructuredOutputCapture<any> = { called: false, value: undefined };
+    const customTools: ToolDefinition[] = [...this.baseTools, ...(options.tools ?? [])];
+
+    if (options.schema) {
+      customTools.push(createStructuredOutputTool({ schema: options.schema, capture }) as unknown as ToolDefinition);
+    }
+
+    const agentDir = getAgentDir();
+    const { session } = await createAgentSession({
+      cwd: this.cwd,
+      agentDir,
+      sessionManager: SessionManager.inMemory(this.cwd),
+      settingsManager: SettingsManager.create(this.cwd, agentDir),
+      customTools,
+      ...this.sessionOptions,
+    });
+
+    let removeAbortListener: (() => void) | undefined;
+    try {
+      if (options.signal?.aborted) throw new Error("Subagent was aborted");
+      if (options.signal) {
+        const onAbort = () => void session.abort();
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        removeAbortListener = () => options.signal?.removeEventListener("abort", onAbort);
+      }
+
+      await session.prompt(this.buildPrompt(prompt, options as AgentRunOptions<any>, Boolean(options.schema)));
+      if (options.signal?.aborted) throw new Error("Subagent was aborted");
+
+      if (options.schema) {
+        if (!capture.called) {
+          throw new Error("Subagent finished without calling structured_output");
+        }
+        return capture.value as AgentRunResult<TSchemaDef>;
+      }
+
+      return this.lastAssistantText(session.messages) as AgentRunResult<TSchemaDef>;
+    } finally {
+      removeAbortListener?.();
+      session.dispose();
+    }
+  }
+
+  private buildPrompt(prompt: string, options: AgentRunOptions<any>, structured: boolean): string {
+    const parts = [
+      this.instructions,
+      options.instructions,
+      options.label ? `Task label: ${options.label}` : undefined,
+      prompt,
+    ].filter(Boolean);
+
+    if (structured) {
+      parts.push(
+        [
+          "Final output contract:",
+          "- Your final action MUST be a structured_output tool call.",
+          "- The structured_output arguments are the return value of this subagent.",
+          "- Do not emit a prose final answer instead of structured_output.",
+          "- If you need to inspect files or run commands first, do so, then call structured_output exactly once.",
+        ].join("\n"),
+      );
+    }
+
+    return parts.join("\n\n");
+  }
+
+  private lastAssistantText(messages: unknown[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i] as Partial<AssistantMessage> | undefined;
+      if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+      const text = message.content
+        .filter((part): part is TextContent => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+      if (text.trim()) return text;
+    }
+    return "";
+  }
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * Workflow 运行时配置。
+ *
+ * 优先级：JSON 配置文件（由 /workflow-config 斜杠命令写入）> 环境变量兜底 > 默认值。
+ * 环境变量仅作为兜底支持（PI_WORKFLOW_BACKEND / PI_WORKFLOW_ASYNC）。
+ */
+export type WorkflowBackend = "workflow" | "subagent";
+
+export interface WorkflowConfig {
+	/** 执行后端：内置 workflow agent 或 pi-interactive-subagents 子会话。 */
+	backend: WorkflowBackend;
+	/** 是否以后台异步模式运行 workflow（注册 workflow_cancel 工具）。 */
+	async: boolean;
+}
+
+const DEFAULTS: WorkflowConfig = { backend: "workflow", async: false };
+
+/** 配置文件路径：<agentDir>/extensions/pi-dynamic-workflows/config.json */
+export function configPath(): string {
+	return join(getAgentDir(), "extensions", "pi-dynamic-workflows", "config.json");
+}
+
+function fromEnv(): WorkflowConfig {
+	const config = { ...DEFAULTS };
+	if (process.env.PI_WORKFLOW_BACKEND === "subagent") config.backend = "subagent";
+	if (process.env.PI_WORKFLOW_ASYNC === "true") config.async = true;
+	return config;
+}
+
+/** 读取配置：JSON 文件覆盖环境变量兜底值。文件缺失或损坏时静默回退到环境变量/默认值。 */
+export function loadConfig(): WorkflowConfig {
+	const config = fromEnv();
+	try {
+		if (!existsSync(configPath())) return config;
+		const parsed = JSON.parse(readFileSync(configPath(), "utf-8")) as Partial<WorkflowConfig>;
+		if (parsed.backend === "workflow" || parsed.backend === "subagent") config.backend = parsed.backend;
+		if (typeof parsed.async === "boolean") config.async = parsed.async;
+	} catch {
+		// 配置损坏：保留环境变量兜底值，不抛出。
+	}
+	return config;
+}
+
+/** 合并写入配置，返回写入后的完整配置。 */
+export function saveConfig(partial: Partial<WorkflowConfig>): WorkflowConfig {
+	const merged: WorkflowConfig = { ...loadConfig(), ...partial };
+	const path = configPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`, "utf-8");
+	return merged;
+}