@zhushanwen/pi-subagent-workflow 9.1.1 → 9.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "9.1.1",
+  "version": "9.2.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -58,12 +58,12 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.17.0",
     "@zhushanwen/session-delivery": "1.0.0",
+    "@zhushanwen/extension-protocol": "0.17.0",
     "@zhushanwen/pi-ext-guards": "0.4.2",
+    "@zhushanwen/pi-notify-ledger-host": "0.2.3",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-notify-ledger-host": "0.2.2",
-    "@zhushanwen/subagent-core": "1.1.0",
+    "@zhushanwen/subagent-core": "1.2.0",
     "@zhushanwen/pi-subagent-cli": "0.5.0",
     "@zhushanwen/zcode-subagent-cli": "0.4.4"
   },

package/src/injectors/__tests__/workflow-list-injector.test.ts

@@ -243,7 +243,7 @@ describe("formatAgentList CA2 快照（agent guide 壳自有文案唯一字节
 		// guide 段硬编码（锁文本）：期望值不插值生产常量——改写 SUBAGENT_LIST_GUIDE
 		// 即红灯，避免「两侧同源插值」下文案漂移无守卫
 		expect(out).toBe(
-			`\n\n<available_subagents>\nThe following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.\n${expectedItems.join("\n")}\n</available_subagents>`,
+			`\n\n<available_subagents>\nThe following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, pass the <location> path from this list as the agent param (usually the right choice); an absolute .md path outside this list also works if the file is a readable agent definition. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.\n${expectedItems.join("\n")}\n</available_subagents>`,
 		);
 
 		// location 前缀替换（资产来源迁移：pi-sw 安装目录 → core 包）后其余字节零变化

package/src/injectors/subagent-list-injector.ts

@@ -43,7 +43,7 @@ import { createResourceListInjector } from "./resource-list-injector.ts";
  * 动态指引经 task 文本 / appendSystemPrompt 参数承载。
  */
 export const SUBAGENT_LIST_GUIDE =
-	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, ONLY use agents from this list — pass the <location> path (absolute .md path) as the agent param. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
+	"The following subagents are available. PRIORITY: when a task involves reading 3+ files, writing 100+ lines, parallel research, or specialized review, delegate to a matching subagent FIRST instead of doing it yourself — this keeps your context focused on orchestration. Do NOT call list to discover available subagents; use list only for running state. When using the subagent tool, pass the <location> path from this list as the agent param (usually the right choice); an absolute .md path outside this list also works if the file is a readable agent definition. If no agent matches your task, omit agent (a general-purpose agent is used) and put all role-specific instructions in the task text.";
 
 /**
  * agent 清单实例：缓存生命周期 / 三 handler 经工厂骨架；装配循环经 assemble 覆写

package/src/interface/gui/subagent-actions.ts

@@ -139,7 +139,11 @@ export function buildGuiComponent(
     const listResp = input.domain;
     return guiComponent("list-tree", {
       items: listResp.response.items.map((it) => ({
-        label: it.slug ? `${it.agent} · ${it.slug} · ${it.subagentId}` : `${it.agent} · ${it.subagentId}`,
+        // GUI 详情层：label 保留完整 agent ref（摘要短名的取舍见 TUI compact/expanded
+        // 分层——GUI list-tree 是详情展示，全路径信息优先）
+        label: it.slug
+          ? `${it.agent} · ${it.slug} · ${it.subagentId}`
+          : `${it.agent} · ${it.subagentId}`,
         status: mapRunStatus(it.status),
         icon: mapRunIcon(it.status),
       })),

package/src/interface/tool/__tests__/tool-render.test.ts

@@ -200,7 +200,7 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
     expect(expanded.join("\n")).toContain("/tmp/sessions/old-abc.jsonl");
   });
 
-  it("list：expanded 在 compact 之上追加 session 行（差异锁定）", () => {
+  it("list：expanded agent 用完整 ref、并追加 session 行；compact agent 用 basename 短名（分层锁定）", () => {
     const details = {
       action: "list",
       subagentId: null,
@@ -209,7 +209,7 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
         running: 1,
         items: [{
           subagentId: "sa-1",
-          agent: "worker",
+          agent: "/Users/x/.agents/agents/worker.md",
           slug: "scan",
           status: "running",
           duration: 12,
@@ -218,10 +218,18 @@ describe("renderSubagentResult — expanded 与 compact 的分支关系（字节
       },
     };
     const { compact, expanded } = renderBoth(details);
+    // compact：basename 短名（无目录、无 .md），无 session 行。强断言带边界形态：
+    // agent 值以完整 accent 包裹出现（防 "worker" 作为其他字段子串命中弱化回归）
+    expect(compact.join("\n")).toMatch(/<accent>worker<\/accent>/);
+    expect(compact.join("\n")).not.toContain("/Users/x/.agents/");
+    expect(compact.join("\n")).not.toContain(".md");
     expect(compact.join("\n")).not.toContain("session: ");
+    // expanded：agent 完整 ref（详情层）+ session 路径行
+    expect(expanded.join("\n")).toContain("/Users/x/.agents/agents/worker.md");
+    expect(expanded.join("\n")).toContain("session: ");
     expect(expanded.join("\n")).toContain("/tmp/sessions/sa-1.jsonl");
-    expect(compact.join("\n")).not.toContain("/tmp/sessions/sa-1.jsonl");
-    // compact 的行是 expanded 的前缀（追加不修改既有行）
-    expect(expanded.slice(0, compact.length)).toEqual(compact);
+    // 标题行两态一致（首行），差异只在 item agent 行与追加 session 行
+    expect(expanded[0]).toBe(compact[0]);
+    expect(expanded.length).toBe(compact.length + 1);
   });
 });

package/src/interface/tool/__tests__/tool-workflow.test.ts

@@ -906,3 +906,66 @@ describe("TC3i: 宿主 TOOL_TOP_LEVEL reservedKeys 接线锚（M-3 回归）", (
     expect(argKeysFromMeta(rflParams(), OPT).exact.has("name")).toBe(false);
   });
 });
+
+// ══════════════════════════════════════════════════════════════
+// renderCall 标题行（displayWorkflowName 短名 + runId/slug 不受影响）
+// ══════════════════════════════════════════════════════════════
+//
+// 锁 2026-09 display 分层：name 是绝对 .js 路径，标题行只出 basename 短名
+// （displayWorkflowName）；runId 截断预览与 slug 后缀形态不变。
+
+/** 最小 theme stub（fg/bold 直包文本——断言不依赖真实着色映射）。 */
+function makeRenderTheme(): Record<string, (color: string | ((t: string) => string), text?: string) => string> {
+  return {
+    fg: (_color, text) => (typeof text === "string" ? `<${_color}>${text}</${_color}>` : ""),
+    bold: (text) => (typeof text === "string" ? `<b>${text}</b>` : ""),
+  } as never;
+}
+
+/** pi-tui Text 反射取构造串（tool-render.test.ts 同款 helper——本文件独立内联）。 */
+function textOf(component: unknown): string {
+  const obj = component as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    const v = obj[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return "";
+}
+
+describe("renderCall 标题行：displayWorkflowName 短名 + runId/slug 不受影响", () => {
+  const tool = captureWorkflowTool(makeDeps(stubRegistry()), { isProcessing: false });
+  const theme = makeRenderTheme();
+
+  it("绝对路径 name → basename 短名（去 .js、去目录）", () => {
+    const out = textOf(
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall({ action: "run", name: "/home/u/wf/batch-report.js" }, theme),
+    );
+    expect(out).toMatch(/batch-report<\/accent>/); // name 落在 accent 段收口前（前缀空格也在段内）
+    expect(out).not.toContain("/home/u/wf/");
+    expect(out).not.toContain(".js");
+  });
+
+  it("runId / slug 后缀不受短名影响（runId 截断预览 + slug 全文）", () => {
+    const out = textOf(
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall(
+          { action: "run", name: "/home/u/wf/batch-report.js", slug: "nightly", runId: "wf-run-0123456789" },
+          theme,
+        ),
+    );
+    // 短名 + slug 全文在位
+    expect(out).toContain("batch-report");
+    expect(out).toContain("nightly");
+    // runId 只出截断预览（ID_PREVIEW_LENGTH = 8 → "wf-run-0"），不泄漏全文
+    expect(out).toContain("wf-run-0");
+    expect(out).not.toContain("wf-run-0123456789");
+  });
+
+  it("缺 name（status 等无参 action）不崩、不出短名", () => {
+    expect(() =>
+      (tool as unknown as { renderCall: (args: Record<string, unknown>, theme: unknown) => unknown })
+        .renderCall({ action: "status" }, theme),
+    ).not.toThrow();
+  });
+});

package/src/interface/tool/subagent-tool-schema.ts

@@ -55,7 +55,7 @@ export const SubagentParams = Type.Object({
     maxLength: SLUG_MAX_LENGTH,
   })),
   agent: Type.Optional(Type.String({
-    description: 'Agent ref: absolute path to the agent .md file (use <location> from <available_subagents>). If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context. Do not invent names — only use paths from the injected list.',
+    description: 'Agent ref: absolute path to an agent .md file — usually a <location> from <available_subagents>, but ANY absolute .md path works if the file is a readable agent definition (the list is not required). Relative paths and bare names are rejected. If omitted, defaults to "general-purpose" — a generic agent that inherits the main agent\'s model and project context.',
   })),
   model: Type.Optional(Type.String({
     description: 'Model override in "provider/modelId" format. CASE-SENSITIVE: the string must equal a registry entry exactly, including letter case (e.g. "zai-coding-cn/GLM-5.3-Flash", NOT "zai-coding-cn/glm-5.3-flash"). A non-exact match is rejected immediately with "Did you mean" suggestions — retry with the exact suggested string; the system never auto-corrects your input. Resolution order (top wins): (1) this param, (2) agent .md frontmatter model, (3) the main agent\'s current model (zero-config default). An explicit model (param or frontmatter) that is missing or unauthorized THROWS — there is no silent fallback to the main model. Omit this param to inherit the main model.',

package/src/interface/tool/subagent-tool.ts

@@ -149,7 +149,7 @@ export function registerSubagentTool(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "subagent",
     label: "Subagent",
-    promptSnippet: "Delegate to specialized subagents (agentRef = absolute .md path from <available_subagents>)",
+    promptSnippet: "Delegate to specialized subagents (agentRef = absolute .md path, e.g. a <location> from <available_subagents>)",
     description: `Delegate a task to a specialized subagent — when to delegate rather than do it yourself.
 
 CRITICAL — executionMode "sequential": multiple \`subagent\` calls in the SAME message run one-after-another. For concurrency, start runs in background and tasks run concurrently in the pool (default maxConcurrent=6).

package/src/interface/tool/tool-render.ts

@@ -230,7 +230,8 @@ function buildCompactLines(d: SubagentToolResult, theme: ThemeLike): string[] {
 /**
  * 展开视图行内容生成。除下列两个特例外与 compact 逐字节相同（一次性 block 无
  * 细节可展开），测试锁字节等价：
- * - list：compact 结果之上每 item 追加 sessionFile 路径行（renderListExpanded）
+ * - list：每 item agent 用完整 ref（compact 用 basename 短名），并追加 sessionFile 路径行
+ *   （renderListExpanded）
  * - fork-from：源文件用完整路径（compact 用 basename 短标签）
  */
 function buildExpandedLines(d: SubagentToolResult, theme: ThemeLike): string[] {
@@ -309,8 +310,14 @@ function getStringText(item: unknown): string | undefined {
 // list 渲染 helper（action:"list" 分支）
 // ============================================================
 
-/** list compact：标题行 + 每行一个 item 摘要（glyph + agent + slug + mode + status + duration）。 */
-function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number): string[] {
+/**
+ * list compact：标题行 + 每行一个 item 摘要（glyph + agent + slug + mode + status + duration）。
+ *
+ * agent 展示分层（同 fork-from 先例：compact 短标签 / expanded 完整路径——摘要行
+ * 单行宽度优先，详情行信息完整优先）：`shortAgent: false`（expanded）输出完整 ref。
+ */
+function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number, opts?: { shortAgent?: boolean }): string[] {
+  const shortAgent = opts?.shortAgent ?? true;
   if (resp.items.length === 0) {
     return [truncLine(theme.fg("dim", `No subagents (running: ${resp.running})`), width)];
   }
@@ -323,16 +330,21 @@ function renderListCompact(resp: ListResponse, theme: ThemeLike, width: number):
     const mode = "bg";
     // slug 非空时在 agent 后展示（· 分隔），空串时省略。
     const slugPart = it.slug ? `${theme.fg("dim", " · ")}${theme.fg("accent", it.slug)}` : "";
-    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", it.agent)}${slugPart}`
+    // compact 摘要：basename 短名（同 renderSubagentCall 标题行）；expanded 详情：完整 ref
+    const agent = shortAgent ? displayAgentName(it.agent) : it.agent;
+    const line = `${theme.fg(glyph.color, icon)} ${theme.fg("accent", agent)}${slugPart}`
       + ` ${theme.fg("dim", `· ${mode} · ${it.status} · ${formatElapsedSeconds(it.duration)}`)}`;
     lines.push(truncLine(`${STREAM_PREFIX}${line}`, width));
   }
   return lines;
 }
 
-/** list expanded：compact 基础上每 item 追加 sessionFile 路径行。 */
+/**
+ * list expanded：compact 基础之上每 item agent 用完整 ref（详情层信息优先），并追加
+ * sessionFile 路径行。
+ */
 function renderListExpanded(resp: ListResponse, theme: ThemeLike, width: number): string[] {
-  const lines = renderListCompact(resp, theme, width);
+  const lines = renderListCompact(resp, theme, width, { shortAgent: false });
   for (const it of resp.items) {
     if (it.sessionFile) {
       lines.push(truncLine(`${theme.fg("dim", `${FOOTER_PREFIX}session: `)}${it.sessionFile}`, width));

package/src/interface/tool/tool-subagents.ts

@@ -82,7 +82,7 @@ const SubagentsParams = Type.Object({
   }),
   agents: Type.Optional(Type.String({
     description:
-      "Comma-separated absolute paths to agent .md files (use <location> from <available_subagents>). " +
+      "Comma-separated absolute paths to agent .md files (usually <location> values from <available_subagents>; arbitrary absolute .md paths also work). " +
       "One path applies to every member; N paths map one-to-one onto tasks in the same order. " +
       "When more than one path is given it MUST equal the number of tasks — a mismatch fails the run fast (never a silent persona swap). " +
       "Omit for the default (general-purpose) executor.",

package/src/interface/tool/tool-workflow.ts

@@ -30,6 +30,7 @@ import { type Static, Type } from "typebox";
 
 import { SLUG_MAX_LENGTH } from "@zhushanwen/subagent-core";
 import { THINKING_ORDER } from "@zhushanwen/subagent-core";
+import { displayWorkflowName } from "@zhushanwen/subagent-core";
 import type { LauncherDeps } from "@zhushanwen/subagent-core";
 import { abortRun, resumeRun, runWorkflow } from "@zhushanwen/subagent-core";
 import type { ResumeRunOptions } from "@zhushanwen/subagent-core";
@@ -86,7 +87,7 @@ const WORKFLOW_ACTIONS: readonly WorkflowAction[] = [
 const WorkflowParams = Type.Object({
   action: StringEnum(WORKFLOW_ACTIONS, { description: "Workflow action to execute" }),
   name: Type.Optional(
-    Type.String({ description: "Workflow ref: absolute path to the .js script — use the <location> value from <available_workflows> (bare names are rejected; run action)" }),
+    Type.String({ description: "Workflow ref: absolute path to a .js script — normally the <location> of a workflow from <available_workflows>, but ANY absolute .js path works if the file declares `@pi-meta kind: \"workflow\"` (the list is not required). Relative paths and bare names are rejected (run action)" }),
   ),
   slug: Type.Optional(
     Type.String({
@@ -224,7 +225,7 @@ export function registerWorkflowTool(
       "<available_workflows> (injected each turn). For parameter details, read the <location> " +
       "script file (script header has @pi-meta parameters + usage + phases). Do NOT use " +
       "workflow-script generate for patterns already covered by available workflows.",
-      "run: pass the workflow ref as name — ALWAYS the <location> absolute .js path from <available_workflows> (bare names are rejected with a not-found error listing locations).",
+      "run: pass the workflow ref as name — normally the <location> absolute .js path from <available_workflows>, but any absolute .js path with a valid @pi-meta also works (the list is not required). Bare names and relative paths are rejected with a not-found error listing locations.",
       "DO NOT bash sleep or poll status after starting — results appear automatically via notifyDone.",
       "Runs are one-shot: there is no pause — to stop a run early use abort; for a fresh result start a new run. " +
       "resume is ONLY for runs whose status is interrupted (crash or session-switch during execution): it replays " +
@@ -241,7 +242,7 @@ export function registerWorkflowTool(
       "Model/thinkingLevel: omit by default (inherit main agent's model). Only set model/thinkingLevel when the user explicitly requests a specific model or thinking depth for this run.",
       "Anti-patterns: Flattening args sub-fields (task/items/...) to the top level — they belong inside args. Calling {\"action\":\"run\"} without name.",
       "CRITICAL: For orchestration patterns, ALWAYS use action:run with the <location> absolute " +
-      "path of a listed workflow — NEVER use workflow-script action:generate to recreate patterns " +
+      "path of the matching listed workflow — NEVER use workflow-script action:generate to recreate patterns " +
       "already covered by available workflows. workflow-script generate is ONLY for novel patterns.",
     ],
     parameters: WorkflowParams,
@@ -296,7 +297,9 @@ export function registerWorkflowTool(
 
     renderCall(args: Record<string, unknown>, theme: Theme, _context?: unknown) {
       const action = String(args.action ?? "");
-      const name = args.name ? ` ${String(args.name)}` : "";
+      // workflow ref 是绝对路径，标题行显示取 basename 短名（displayWorkflowName，
+      // 与 subagent 标题行的 displayAgentName 对称）；runId/slug 不受影响。
+      const name = args.name ? ` ${displayWorkflowName(String(args.name))}` : "";
       // run action 可选 slug：在 name 后追加 · slug（accent 色）
       const slug = optionSlugSuffix(args.slug, theme);
       const runId = args.runId ? ` ${String(args.runId).slice(0, ID_PREVIEW_LENGTH)}` : "";
@@ -325,7 +328,7 @@ export async function actionRun(
   const name = params.name;
   if (!name) {
     throw new Error(
-      "run requires 'name' parameter (absolute .js path from <available_workflows> <location>). Correct: {\"action\":\"run\",\"name\":\"<ref>\"}",
+      "run requires 'name' parameter (an absolute .js path, e.g. a <location> from <available_workflows>). Correct: {\"action\":\"run\",\"name\":\"<ref>\"}",
     );
   }
   // 弱模型常见误用（P0 静默失败）：把 task/items 等 args 子字段平铺到 workflow params