@wolido/async-subagent-isolation 1.2.0 → 1.3.0

package/ADVANCED.en.md

@@ -139,6 +139,8 @@ Once the subagent finishes, its result is pushed into the conversation:
 
 Status enumeration: **成功** (success, exit=0) / **失败** (failure, exit≠0 or stopReason=error) / **超时** (timeout, activity_timeout or hard_timeout) / **已取消** (cancelled, aborted or killed_on_shutdown).
 
+**Duration**: the `- 耗时:` line shows the subagent's real run time. When a result exists, it is the actual process run time (`finishedAt - startedAt`); when the result is null (user/agent cancel, session shutdown, internal error), it is measured from dispatch time instead. The format is `MM:SS`, or `H:MM:SS` at one hour and beyond (hours not zero-padded). All four terminal states (success, failure, timeout, cancelled) carry the duration in both the envelope and the TUI notification card.
+
 "Cancelled" has three sub-cases with different envelope bodies:
 - User cancelled via `/subagent-cancel` (cancelledBy: user) → body states this is a deliberate user action; the main agent must NOT auto-retry and must ask the user before re-dispatching.
 - Main agent cancelled via the `subagent` tool with `action="cancel"` (cancelledBy: agent) → body states the task was cancelled by the main agent via the subagent tool (action=cancel).
@@ -148,7 +150,7 @@ When the main agent receives a "已取消" notification, it should distinguish t
 
 **In-flight block**: the "在途任务" list in the envelope's metadata section lists the **other** background tasks still running (this task is removed from the registry before the envelope is built, so it never appears in its own list). Its format is `在途任务: N` followed by one `- taskId (agent): task description` line per task, or `当前无在途任务。` when none remain. It deliberately carries **no elapsed time** (it answers "what is still running", not "how long has it run"). The main agent uses it to know how many tasks are still outstanding — while the count is non-zero, do not report "all done" to the user.
 
-The full output enters the LLM context (not truncated). The `details` carries structured data (taskId, agent, status, exitCode, stopReason, usage, sessionId, full output) for programmatic consumption; it does not enter the LLM context.
+The full output enters the LLM context (not truncated). The `details` carries structured data (taskId, agent, status, exitCode, stopReason, durationMs (required, run time in milliseconds), usage, sessionId, full output) for programmatic consumption; it does not enter the LLM context.
 
 ### Notification delivery
 
@@ -166,6 +168,8 @@ While subagents run, a progress widget appears above the TUI editor, listing all
 ● 01912345-abcd... coder    ⚡ read...         01:23
 ```
 
+The widget's time is a live "alive since" clock (`formatElapsed`, `MM:SS` only, overflowing past 99 minutes); the envelope and notification card show the final run duration (`formatDuration`). The two coexist with different semantics.
+
 The taskId in the widget row can be copied for `/subagent-result` (view full result) or `/subagent-cancel` (cancel the task).
 
 ### Cancelling background tasks

package/ADVANCED.md

@@ -139,6 +139,8 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 
 状态枚举：**成功**（exit=0）/ **失败**（exit≠0 或 stopReason=error）/ **超时**（activity_timeout 或 hard_timeout）/ **已取消**（aborted 或 killed_on_shutdown）。
 
+**耗时**：`- 耗时:` 行是子 agent 的真实运行时长。有结果时取进程实际启动到结束（`finishedAt - startedAt`）；取消（用户/agent/会话关闭）或内部错误导致无结果返回时，改从派发时刻起算。格式为 `MM:SS`，≥1 小时为 `H:MM:SS`（小时不补零）。四种状态（成功/失败/超时/已取消）的信封与 TUI 通知卡片都带耗时。
+
 "已取消"分三种情况，信封正文不同：
 - 用户通过 `/subagent-cancel` 取消（cancelledBy: user）→ 正文注明"属用户主动操作。请勿自动重新派发；如需重新派发，先询问用户。"
 - 主 agent 通过 `subagent` 工具（`action="cancel"`）取消（cancelledBy: agent）→ 正文注明"该任务已由主 agent 通过 subagent 工具（action=cancel）取消。"
@@ -148,7 +150,7 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 
 **在途任务块**：信封元信息区的"在途任务"列表列出**其余**仍在运行的后台任务（本任务在构建信封前已从注册表移除，故不包含自身），格式为 `在途任务: N` 加每行 `- taskId (agent名): 任务描述`，无在途任务时为"当前无在途任务。"列表**不含耗时**（回答"还有什么在跑"，而非"跑了多久"）。主 agent 据此知道还有几个任务没回来：剩余不为 0 时，不要向用户汇报"全部完成"。
 
-结果全量进入 LLM 上下文（不截断）。`details` 携带结构化数据（taskId、agent、status、exitCode、stopReason、usage、sessionId、完整输出），不参与 LLM 上下文，供程序消费。
+结果全量进入 LLM 上下文（不截断）。`details` 携带结构化数据（taskId、agent、status、exitCode、stopReason、durationMs（耗时毫秒数，必填）、usage、sessionId、完整输出），不参与 LLM 上下文，供程序消费。
 
 ### 通知投递
 
@@ -166,6 +168,8 @@ TUI 模式下 `subagent` 立即返回如下回执（不是结果！）：
 ● 01912345-abcd... coder    ⚡ read...         01:23
 ```
 
+widget 行的耗时是"存活至今"的实时时钟（`formatElapsed`，仅 `MM:SS`，可溢出 99 分钟）；信封与通知卡片的耗时是终态运行时长（`formatDuration`）。两者并存，语义不同。
+
 widget 行中的 taskId 可直接复制，用于 `/subagent-result` 查看结果或 `/subagent-cancel` 取消任务。
 
 ### 取消后台任务

package/README.en.md

@@ -180,10 +180,11 @@ The `[subagent-result]` notification is **self-contained** — it carries everyt
 ```
 
 - **Status**: `成功` (success) / `失败` (failure) / `超时` (timeout) / `已取消` (cancelled).
+- **Duration**: the subagent's real run time (process start to finish; `MM:SS`, or `H:MM:SS` at 1h+), shown for all four states. For cancellations or internal errors with no result, it is measured from dispatch time.
 - **In-flight block**: lists the other background tasks still running (not itself), so the main agent knows how many are outstanding — while the count is non-zero, do not report "all done" to the user.
 - **Full result**: the body enters the LLM context in full, untruncated.
 
-In the TUI, the user sees a **tinted summary card**, not the full result: success green (✓), failure red (✗), timeout/cancelled yellow. The card shows the agent, status, taskId, and usage summary, plus the hint `查看全文: /subagent-result <taskId>`; the full text lives in the task's session file.
+In the TUI, the user sees a **tinted summary card**, not the full result: success green (✓), failure red (✗), timeout/cancelled yellow. The card shows the agent, status, taskId, duration, and usage summary (duration included for all four states), plus the hint `查看全文: /subagent-result <taskId>`; the full text lives in the task's session file.
 
 See [ADVANCED.en.md](ADVANCED.en.md) for the complete envelope format, status semantics, and cancel-origin distinctions.
 

package/README.md

@@ -180,10 +180,11 @@ TUI 模式下 `subagent` **立即返回派发回执**，不阻塞：
 ```
 
 - **状态**：`成功` / `失败` / `超时` / `已取消`。
+- **耗时**：子 agent 的真实运行时长（进程实际启动到结束，格式 `MM:SS`，≥1 小时为 `H:MM:SS`），成功/失败/超时/已取消四种状态都有；取消或内部错误（无结果返回）时从派发时刻起算。
 - **在途任务块**：列出其余仍在运行的后台任务（不含自身），让主 agent 知道还有几个任务没回来——剩余不为 0 时，不要向用户汇报"全部完成"。
 - **完整结果**：正文全量进入 LLM 上下文，不截断。
 
-用户在 TUI 中看到的是**带底色的摘要卡片**，不是全文：成功绿色（✓）、失败红色（✗）、超时/已取消黄色。卡片只显示 agent、状态、taskId 和用量摘要，并提示 `查看全文: /subagent-result <taskId>`；完整结果保存在任务会话文件中。
+用户在 TUI 中看到的是**带底色的摘要卡片**，不是全文：成功绿色（✓）、失败红色（✗）、超时/已取消黄色。卡片显示 agent、状态、taskId、耗时和用量摘要（四种状态均带耗时），并提示 `查看全文: /subagent-result <taskId>`；完整结果保存在任务会话文件中。
 
 信封完整格式、状态语义与取消来源区分见 [ADVANCED.md](ADVANCED.md)。
 

package/examples/pi/agent/master.md

@@ -1,6 +1,6 @@
-# 主 Agent
+# 主 Agent（任务指挥官）
 
-你是项目的主 agent。你的职责是理解需求、制定计划、委派执行。你绝不亲自编辑代码、不执行命令、不写文件。
+你是项目的任务指挥官：团队领导与质量守门员。你的职责是理解需求、制定计划、委派执行、审查产出，对最终交付物的质量负全责。你绝不亲自编辑代码、不执行命令、不写文件；所有执行都委派给子 agent，不达标的结果不交付给用户。
 
 ## 可用子 Agent
 
@@ -45,6 +45,8 @@
     - **输出格式** — 期望的返回结构
     - **验收标准** — 如何判断完成（必须含验证命令及输出）
 
+    其中**输出格式**应要求子 agent 返回以下要素：执行摘要、详细结果、状态（✅ 完成 / ⚠️ 部分 / ❌ 阻塞）、文件变更列表、后续建议。
+
 ### 调用示例
 
 调用 `subagent` tool 时，应把上述五部分内容全部写入 `task` 字段，例如：
@@ -58,6 +60,52 @@
 
 **注意**：`task` 字段必须非空，禁止只传 `agent` 而空传 `task`。如果 `task` 为空，子 agent 将拒绝执行。
 
+## 任务编排原则
+
+拆分与派发任务时：
+
+- **拆到原子级**：每个子 agent 一次只承担一类同质任务（实现归 `coder`、评审归 `reviewer`、写作归 `writer`），不同性质的工作不混在一个任务里。
+- **明确依赖关系**：前一个任务的产出是后一个任务的输入时，必须先等前者完成。
+- **避免过载**：单个子 agent 一次不承担过多职责；任务太大就先拆小再派。
+- **合理并行**：无依赖的任务并行派发，有依赖的串行等待。
+
+## 上下文传递规范
+
+委派时为子 agent 提供的上下文必须做到：
+
+- **充分**：相关素材、约束条件、能力边界、此前反馈全部给足。
+- **结构化**：按核心规则第 8 条的五段结构（背景 / 输入 / 要求 / 输出格式 / 验收标准）组织。
+- **一次给齐**：不让子 agent 拿着不完整的信息开工，事后再补。
+
+上下文应包含的典型要素：
+
+- 任务的来源、背景和目标
+- 相关素材的路径和内容
+- 已知的约束条件（技术、风格、范围等）
+- 子 agent 的能力边界（对照"可用子 Agent"表，不派超出其工具与职责的事）
+- 此前的反馈或调整历史
+- 期望的输出格式与验收标准
+
+## 不代替子 Agent 出解决方案
+
+布置任务时只描述目标、约束和验收标准，不指定具体代码、参数、算法或实现步骤。子 agent 在各自领域比你更专精，你替它出方案，只会限制团队的整体能力上限。说清楚"做什么、做到什么程度"，把"怎么做"留给子 agent。
+
+## 异步工作纪律
+
+子 agent 的结果以 `[subagent-result]` 通知分散、不定序到达。整合时以用户目标为锚，不被通知到达的顺序带着走：
+
+- **同组不齐不交付**：同一目标下的多个子任务，等该组全部返回后统一整合汇报；组内未齐，不提前交付。
+- **先归类再确认**：每条通知到达时，先判断它属于哪个目标组，再据信封"在途任务"块确认该组剩余在途数量，最后归位汇总。
+
+## 质量审查与迭代
+
+子 agent 提交产出后，你必须：
+
+- **实际读取产出**：用 `read` 亲自查看产物，不只看子 agent 自报的总结。
+- **基于实际产出审查**：按看到的真实产出制定针对性的审查维度，不套预设的死清单。
+- **发现问题就打回**：带着具体问题重新派发修改任务，多轮迭代直到真正达标。
+- **不达标不交付**：不完善的结果不展示给用户，这是质量守门员的底线。
+
 ## 隔离说明
 
 子 agent 的进程与你完全独立。你看不到子 agent 内部的工具调用痕迹和中间结果——你只收到 `[subagent-result]` 通知中的最终总结（TUI 模式）或返回值中的内联结果（非 TUI 模式）。你的上下文不会被子 agent 的执行细节污染，始终专注于规划和决策。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wolido/async-subagent-isolation",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "A pi extension that asynchronously delegates tasks to specialized subagents running in isolated pi processes.",
   "license": "MIT",
   "author": "Wolido",

package/src/index.ts

@@ -426,6 +426,10 @@ interface SingleResult {
 	lastPhaseChange: number;
 	thinkingBuffer?: string;
 	sessionId: string;
+	/** Wall-clock start of this run (Date.now() at runSingleAgent entry). */
+	startedAt: number;
+	/** Wall-clock finish, set when the run resolves; absent while running. */
+	finishedAt?: number;
 }
 
 interface SubagentDetails {
@@ -603,6 +607,22 @@ export function formatElapsed(startedAt: number): string {
 	return `${mm}:${ss}`;
 }
 
+/**
+ * Format a finished run's duration (milliseconds) for result notifications.
+ * Unlike formatElapsed (a live "alive since" clock for the progress widget,
+ * MM:SS only and overflowing past 99 minutes), this floors to whole seconds
+ * and supports hours: < 1h -> "MM:SS", >= 1h -> "H:MM:SS" (hours not
+ * zero-padded), 0/negative -> "00:00".
+ */
+export function formatDuration(ms: number): string {
+	if (!Number.isFinite(ms)) return "00:00";
+	const totalSec = Math.max(0, Math.floor(ms / 1000));
+	const hours = Math.floor(totalSec / 3600);
+	const mm = String(Math.floor((totalSec % 3600) / 60)).padStart(2, "0");
+	const ss = String(totalSec % 60).padStart(2, "0");
+	return hours > 0 ? `${hours}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+
 /**
  * Tracks progress of all running subagents and renders it as a widget above
  * the editor. A single 1Hz interval drives widget refreshes; update() only
@@ -919,6 +939,7 @@ async function runSingleAgent(
 	modelOverrides?: Record<string, ModelOverride>,
 	onProcSpawn?: (proc: ChildProcess) => void,
 ): Promise<SingleResult> {
+	const startedAt = Date.now();
 	let effectiveSessionId: string;
 	if (sessionId !== undefined) {
 		const trimmed = sessionId.trim();
@@ -937,6 +958,8 @@ async function runSingleAgent(
 				phase: "idle",
 				lastPhaseChange: Date.now(),
 				sessionId: trimmed,
+				startedAt,
+				finishedAt: Date.now(),
 			};
 		}
 		effectiveSessionId = trimmed;
@@ -959,6 +982,8 @@ async function runSingleAgent(
 			phase: "idle",
 			lastPhaseChange: Date.now(),
 			sessionId: effectiveSessionId,
+			startedAt,
+			finishedAt: Date.now(),
 		};
 	}
 
@@ -1026,6 +1051,7 @@ async function runSingleAgent(
 		phase: "idle",
 		lastPhaseChange: Date.now(),
 		sessionId: effectiveSessionId,
+		startedAt,
 	};
 
 	const emitProgress = () => {
@@ -1098,6 +1124,7 @@ async function runSingleAgent(
 			const finalize = (code: number) => {
 				if (resolved) return;
 				resolved = true;
+				currentResult.finishedAt = Date.now();
 				if (postExitTimer) {
 					clearTimeout(postExitTimer);
 					postExitTimer = undefined;
@@ -1537,6 +1564,13 @@ export interface SubagentResultDetails {
 	stopReason?: string;
 	/** Present only on cancelled tasks: who cancelled ("user" | "agent"). */
 	cancelledBy?: "user" | "agent";
+	/**
+	 * Run duration in milliseconds (>= 0): the real run time
+	 * (finishedAt - startedAt) when a result exists; measured from the
+	 * dispatch time (task.startedAt) when result is null (cancel/internal
+	 * error).
+	 */
+	durationMs: number;
 	usage: UsageStats;
 	sessionId: string;
 	output: string;
@@ -1577,6 +1611,12 @@ export function buildResultEnvelope(
 	const usage: UsageStats =
 		result?.usage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 	const sessionId = result?.sessionId ?? task.taskId;
+	// Real run time when the subagent produced a result; for a null result
+	// (user/agent cancel, session shutdown, internal error) the run never
+	// reported back, so measure from the dispatch time instead.
+	const durationMs = result
+		? Math.max(0, (result.finishedAt ?? Date.now()) - result.startedAt)
+		: Math.max(0, Date.now() - task.startedAt);
 	let body = output;
 	if (!body && result) body = result.errorMessage || result.stderr.trim();
 	// Only genuine failures are labelled "内部错误"; a user cancel or session
@@ -1588,7 +1628,7 @@ export function buildResultEnvelope(
 		"",
 		`- 状态: ${statusWord}`,
 		`- 任务: ${truncateTaskDescription(task.task)}`,
-		`- 耗时: ${formatElapsed(task.startedAt)} · 用量: ${formatUsageStats(usage, result?.model) || "-"}`,
+		`- 耗时: ${formatDuration(durationMs)} · 用量: ${formatUsageStats(usage, result?.model) || "-"}`,
 		`- 会话: ${sessionId}`,
 		"",
 		// 在途 block: completeAsyncTask deletes this task from the registry
@@ -1607,6 +1647,7 @@ export function buildResultEnvelope(
 			exitCode: result?.exitCode ?? null,
 			stopReason,
 			cancelledBy: task.cancelledBy,
+			durationMs,
 			usage,
 			sessionId,
 			output:
@@ -2073,6 +2114,14 @@ export default function (pi: ExtensionAPI) {
 				const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
 				const displayItems = getDisplayItems(r.messages);
 				const finalOutput = getFinalOutput(r.messages);
+				// Run duration, shown only when both timestamps are present (older
+				// results lack them); a typeof check keeps 0ms runs visible and
+				// missing fields from rendering "NaN".
+				const durationStr =
+					typeof r.startedAt === "number" && Number.isFinite(r.startedAt) &&
+					typeof r.finishedAt === "number" && Number.isFinite(r.finishedAt)
+						? formatDuration(r.finishedAt - r.startedAt)
+						: null;
 
 				if (expanded) {
 					const container = new Container();
@@ -2080,6 +2129,7 @@ export default function (pi: ExtensionAPI) {
 					if (isError && r.stopReason) header += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 					if (r.phase !== "idle") header += ` ${theme.fg("warning", formatPhase(r.phase))}`;
 					header += ` ${theme.fg("muted", `[session: ${r.sessionId}]`)}`;
+					if (durationStr) header += ` ${theme.fg("dim", durationStr)}`;
 					container.addChild(new Text(header, 0, 0));
 					if (isError && r.errorMessage)
 						container.addChild(new Text(theme.fg("error", `Error: ${r.errorMessage}`), 0, 0));
@@ -2125,6 +2175,7 @@ export default function (pi: ExtensionAPI) {
 				if (isError && r.stopReason) text += ` ${theme.fg("error", `[${r.stopReason}]`)}`;
 				if (r.phase !== "idle") text += ` ${theme.fg("warning", formatPhase(r.phase))}`;
 				text += ` ${theme.fg("muted", `[session: ${r.sessionId}]`)}`;
+				if (durationStr) text += ` ${theme.fg("dim", durationStr)}`;
 				if (isError && r.errorMessage) text += `\n${theme.fg("error", `Error: ${r.errorMessage}`)}`;
 				if (displayItems.length === 0) {
 					if (!isError || !r.errorMessage) text += `\n${theme.fg("muted", "(no output)")}`;
@@ -2319,6 +2370,11 @@ export default function (pi: ExtensionAPI) {
 			if (details?.taskId) text += ` ${theme.fg("muted", `(taskId: ${details.taskId})`)}`;
 			const usageStr = details ? formatUsageStats(details.usage) : "";
 			if (usageStr) text += ` ${theme.fg("dim", usageStr)}`;
+			// durationMs is typed as a number and 0 is a valid duration, so the
+			// presence check must not be falsy-based; old-shape details without
+			// it simply omit the duration.
+			if (typeof details?.durationMs === "number" && Number.isFinite(details.durationMs))
+				text += ` ${theme.fg("dim", `耗时 ${formatDuration(details.durationMs)}`)}`;
 			if (details?.taskId) text += `\n${theme.fg("muted", `查看全文: /subagent-result ${details.taskId}`)}`;
 			// Background tint mirrors the dispatch-receipt tool rows: success and
 			// failure reuse the tool-row colors; timeout, cancelled and unknown