@esso0428/pi-subagents 0.17.6 → 0.17.8

package/docs/superpowers/plans/2026-09-30-upstream-event-workflow-partial-history.md

@@ -0,0 +1,195 @@
+# 上游事件管理、Workflow 與中途歷史實作計畫
+
+> [!NOTE]
+> **給 agentic workers：** 本計畫以目前 fork `64bbbb0` 與 `upstream/master` `e955e29` 的實際差異為準。所有步驟使用 checkbox 追蹤；不得刪除 fork 的 durable history/recovery 與 ConversationViewer 特性。
+
+**目標：** 接收上游 Workflow、lifecycle/RPC 與 render-cost 改善，同時讓所有子代理 launch path 都留下可重新開啟的 stopped/aborted/partial `.pi-subagents` 歷史。
+
+**架構：** 先將上游功能整合進現有 manager/runner/index seam，再把 durable transcript 附掛下沉到 `AgentManager.spawn()`，使 Agent tool、scheduler、RPC、Workflow 共用同一歷史介面。`.output` 僅是可選的外部串流檔；`.pi-subagents` 是 UI/history/checkpoint 的永久資料源。
+
+**技術：** TypeScript、pi ExtensionAPI、pi-tui、Vitest、worker-thread Workflow runtime、JSONL transcript、atomic checkpoint。
+
+## 全域限制
+
+- 保留套件名稱 `@esso0428/pi-subagents` 與 JSON agent override。
+- 保留 pi peer floor `>=0.80.8`，除非 typecheck 證明不可行且另有相容性處理。
+- `output_transcript: false` 僅停用 temp `.output`，不得停用 `.pi-subagents` durable history。
+- 不刪除 `src/agent-history.ts`、`src/agent-history-list.ts`、`src/agent-recovery.ts`。
+- 不覆蓋 fork 的 ConversationViewer scrollbar、`[preview] [Esc]`、`w` focused-tool preview、in-place Tool Preview。
+- 任何新日期型路徑使用當天 `2026-09-30`。
+- 完成前執行 lint、typecheck、`npm test`、`npm run test:e2e`、build、pack；使用者已明確要求 commit、push、publish。
+
+---
+
+### Task 1：建立上游整合基線
+
+**Files:**
+- Modify: `src/agent-manager.ts`, `src/agent-runner.ts`, `src/agent-types.ts`, `src/types.ts`, `src/settings.ts`
+- Modify: `src/index.ts`, `src/cross-extension-rpc.ts`, `src/output-file.ts`, `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`
+- Add: `src/workflow/*.ts`, `src/ui/workflow-*.ts`, `docs/workflows.md`, `docs/rpc.md`, `examples/workflows/*`
+- Test: upstream workflow/RPC/lifecycle tests selected from `test/workflow-*.test.ts`, `test/rpc-result-consumption.test.ts`, `test/child-session-shutdown.test.ts`
+
+**Interfaces:**
+- Consumes: current fork manager/history/UI interfaces and `upstream/master` workflow/runtime/event contracts.
+- Produces: `SubagentWorkflow` registration, workflow host/runtime/task/journal modules, RPC `consume`, lifecycle event ordering, and RPC activity tracking.
+
+- [ ] **Step 1: Record the merge inventory.**
+
+  In `/tmp/pi-canonical/pi-subagents-work`, compare `git diff --name-status 64bbbb0..upstream/master` and group changes into workflow, lifecycle/RPC, UI, package metadata, and deleted history modules. Treat upstream deletions of fork history/recovery as rejected changes.
+
+- [ ] **Step 2: Integrate upstream workflow/event files without replacing fork metadata.**
+
+  Bring in `src/workflow/`, workflow UI, workflow docs/examples, RPC consume/result-consumption changes, session shutdown ordering, scope-model validation, and RPC-spawn activity tracking. Resolve `src/index.ts`, `src/agent-manager.ts`, `src/agent-runner.ts`, `src/types.ts`, `src/settings.ts`, `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`, and `src/ui/conversation-viewer.ts` manually. Keep `src/nico-overrides.ts` and fork package identity.
+
+- [ ] **Step 3: Keep event semantics explicit.**
+
+  Ensure readiness is emitted only after the extension is bound; normal Agent tool emits `created`, `started`, terminal `completed`/`failed`, compaction emits `compacted`, steering emits `steered`, and shutdown emits `session_shutdown` before child session disposal. RPC-spawned agents must be observable from returned id and must not rely on `created`.
+
+- [ ] **Step 4: Run integration-focused tests.**
+
+  Run:
+  ```bash
+  npx vitest run test/cross-extension-rpc.test.ts test/rpc-result-consumption.test.ts test/rpc-lifecycle-gating.test.ts test/child-session-shutdown.test.ts test/workflow-tool.test.ts test/workflow-runtime.test.ts test/workflow.e2e.test.ts
+  ```
+  Expected: all selected tests pass; failures caused by the history/UI seam remain for Tasks 2–3, not hidden by deleting assertions.
+
+---
+
+### Task 2：把 durable partial history 下沉到 manager seam
+
+**Files:**
+- Modify: `src/agent-manager.ts`
+- Modify: `src/index.ts`, `src/output-file.ts`
+- Modify: `src/agent-history.ts`, `src/agent-history-list.ts`, `src/agent-recovery.ts`
+- Modify: `src/types.ts`
+- Test: `test/agent-manager-history.test.ts`, `test/agent-history.test.ts`, `test/agent-history-list.test.ts`, `test/agent-recovery.test.ts`, `test/output-file-history.test.ts`, new `test/partial-history-lifecycle.test.ts`
+
+**Interfaces:**
+- Consumes: `createAgentHistoryPath`, `agentHistoryLocator`, `writeInitialEntry`, `streamToOutputFile`, `setTranscript`, `checkpoint`, `restoreRecovered`.
+- Produces: every `manager.spawn()` record has a project-local transcript before queue/start; `output_transcript` only controls `.output`; terminal records retain `transcriptPath`.
+
+- [ ] **Step 1: Add one manager-owned durable attach operation.**
+
+  Add a private operation in `AgentManager` that, for a new record, creates `.pi-subagents/agent-transcripts/<safe-id>.jsonl`, writes the initial user entry, assigns `historyFile`/`transcriptPath`, and checkpoints. Make it idempotent so Agent tool callers do not duplicate the initial entry. Invoke it before the external `onSpawned` callback and clean only the checkpoint/record on a failed spawn; do not discard a successfully created transcript.
+
+- [ ] **Step 2: Separate `.output` gating from durable history.**
+
+  Change `attachTranscript()` in `src/index.ts` so `outputTranscript === false` skips only `createOutputFilePath()` and the temp initial entry. It must still use the manager-provided `historyFile` and `transcriptPath`. Keep `streamToOutputFile()` dual-write behavior when `record.outputFile` exists, and ensure no duplicate JSONL entry is written to history.
+
+- [ ] **Step 3: Flush before every terminal checkpoint.**
+
+  In manager stop/abort/queue cancellation, runner completion/error, resume failure, parent abort, and session shutdown paths, call `flushOutput(record)` before `checkpoint(record)`. Preserve status precedence: externally stopped remains `stopped`; hard max-turn interruption becomes `aborted`; provider/length failure becomes `error`; partial assistant text remains in JSONL even when `record.result` is empty.
+
+- [ ] **Step 4: Make history visibly partial and reopenable.**
+
+  Extend `AgentHistoryStatus`/formatting only as needed to label `stopped`, `aborted`, and `error` as terminal partial-capable states. Keep `canOpenAgentHistory()` based on live session or durable locator. In `ConversationViewer`, use the persisted status/read-only source and show a concise status marker in the header/footer without removing `[preview] [Esc]` or existing scrollbar geometry.
+
+- [ ] **Step 5: Add path matrix regression tests.**
+
+  Cover:
+  - tool call in progress followed by `manager.abort()`;
+  - queued agent cancellation;
+  - provider error after an assistant partial delta;
+  - max-turn abort/steer;
+  - parent signal abort and `abortAll()`;
+  - manager restore of running checkpoint as stopped;
+  - scheduler and RPC spawn creating `.pi-subagents` history;
+  - `output_transcript: false` still retaining durable history;
+  - history menu and viewer reopening after live session disposal.
+
+  Run the focused history/lifecycle tests before proceeding.
+
+---
+
+### Task 3：合併 UI render-cost 與事件刷新防閃動
+
+**Files:**
+- Modify: `src/ui/conversation-viewer.ts`
+- Modify: `src/ui/agent-widget.ts`, `src/ui/fleet-list.ts`
+- Test: `test/ui/conversation-viewer.test.ts`, `test/conversation-viewer.test.ts`, `test/agent-widget.test.ts`, `test/fleet-list.test.ts`, `test/perf/render-invariants.perf.test.ts` if integrated
+
+**Interfaces:**
+- Consumes: `ConversationTimeline` cache, fork parent-owned `FullToolPreview`, existing deferred/coalesced refresh behavior, upstream `3d91023` render bound.
+- Produces: stable render cost under rapid text/tool events, no nested overlay/input theft, and regression evidence for the original Tool Output failure.
+
+- [ ] **Step 1: Port only the upstream render-cost changes.**
+
+  Inspect upstream `3d91023` and port bounded hidden-tail/truncation and Markdown fallback behavior into the fork's current viewer. Do not replace the fork's scrollbar rail, header action hitboxes, or `openFocusedToolPreview()` path.
+
+- [ ] **Step 2: Coalesce live refreshes.**
+
+  On session event bursts, invalidate only changed timeline/cache state and schedule one `requestRender()` per event-loop turn. Ensure preview mode owns all input/mouse events and returns to the parent viewer without a nested `ctx.ui.custom` overlay.
+
+- [ ] **Step 3: Test the event sequence.**
+
+  Assert that repeated `message_update`/tool activity does not rebuild unchanged rows indefinitely, that the visible scrollbar thumb remains stable, that Tool Output cannot close the underlying subagent panel, and that `Esc`/`q` restore parent focus. Run all focused UI tests.
+
+---
+
+### Task 4：文件、文件說明與相容性整理
+
+**Files:**
+- Modify: `README.md`, `CHANGELOG.md`, `AGENTS.md`
+- Modify: `docs/rpc.md`, `docs/workflows.md`
+- Add/modify: `examples/workflows/*`
+- Preserve: `package.json` identity and peer floor unless verification requires a documented change
+
+**Interfaces:**
+- Consumes: implemented lifecycle/workflow/history behavior and test evidence.
+- Produces: user-facing documentation that explains event channels, Workflow ownership, durable partial history, and `.output` opt-out distinction.
+
+- [ ] **Step 1: Document partial-history guarantees.**
+
+  State that `.pi-subagents` is always the durable diagnostic/history source, including stopped/aborted/error/partial runs; `output_transcript` controls only the temp `.output` mirror. Document reopenability and status labels.
+
+- [ ] **Step 2: Reconcile upstream docs.**
+
+  Add the upstream RPC/Workflow usage and caveats, including RPC readiness, no `created` guarantee for RPC spawns, workflow-owned hidden children, and journal replay rules. Keep fork branding and JSON override instructions.
+
+- [ ] **Step 3: Add Unreleased entries.**
+
+  Add separate changelog bullets for Workflow/event management, durable partial history, and UI render stability. Do not rewrite released sections.
+
+---
+
+### Task 5：完整驗證、版本、commit、push、publish
+
+**Files:**
+- Modify: `package.json`, `package-lock.json`, `CHANGELOG.md`, `README.md` only if release metadata requires it
+- Test: all repository gates
+
+- [ ] **Step 1: Run the full local gates from the canonical checkout.**
+
+  ```bash
+  npm run lint
+  npm run typecheck
+  npm test
+  npm run test:e2e
+  npm run build
+  npm pack --dry-run
+  ```
+  Fix every failure; do not weaken durable-history, RPC lifecycle, Workflow, or UI regression assertions.
+
+- [ ] **Step 2: Select a release version.**
+
+  Because Workflow and lifecycle management are notable additions, update the package to the next minor version after `0.17.6` only after all gates pass. Move Unreleased entries into that version and create a fresh Unreleased section.
+
+- [ ] **Step 3: Commit the complete integration.**
+
+  ```bash
+  git add docs src test README.md CHANGELOG.md package.json package-lock.json AGENTS.md examples
+  git commit -m "feat: integrate upstream workflows and durable partial history"
+  ```
+
+- [ ] **Step 4: Push and publish only after verification.**
+
+  ```bash
+  git push origin master
+  npm publish
+  ```
+  Then independently verify:
+  ```bash
+  git ls-remote origin refs/heads/master
+  npm view @esso0428/pi-subagents version dist-tags.latest
+  ```
+  Confirm the remote commit and npm version match the committed release.

package/docs/superpowers/specs/2026-09-30-upstream-event-workflow-partial-history-design.md

@@ -0,0 +1,49 @@
+# 上游事件管理、Workflow 與中途歷史設計規格
+
+## 目標
+
+在保留 fork 既有 JSON agent override、ConversationViewer scrollbar、in-place Tool Output preview 與 `.pi-subagents` 本地資料層的前提下，接收上游的 Workflow 與 lifecycle/RPC 事件管理；任何子代理即使被停止、逾時、達到 turn limit、父程序中斷或 session shutdown，都要留下可重新開啟、可解釋的中途歷史。
+
+## 範圍
+
+### 必須接收
+
+- 上游 `SubagentWorkflow`：`agent`、`parallel`、`pipeline`、`workflow`、`phase`、`log`、schema/gate、retry/resume、journal、saved workflow、worker-thread sandbox、Workflow UI。
+- 上游 lifecycle/RPC 管理：`subagents:ready`、`created`、`started`、`completed`、`failed`、`steered`、`compacted`、`session_shutdown`，以及 `ping`、`spawn`、`stop`、`consume` reply channels。
+- 上游 RPC spawned agent 的 activity tracking、scopeModels 驗證、completion consume 去重與 shutdown 順序。
+- 上游 ConversationViewer render-cost bound；但不覆蓋 fork 已有的 scrollbar、`[preview] [Esc]`、focused-tool preview 與 in-place overlay 行為。
+
+### 必須保留或強化
+
+- `src/agent-history.ts`、`src/agent-history-list.ts`、`src/agent-recovery.ts` 與相關測試不可因上游刪檔而移除。
+- `.pi-subagents/agent-transcripts/<agent-id>.jsonl` 是 UI 與診斷所需的 durable source of truth；`.output` 是可選的 Claude-compatible side transcript。`output_transcript: false` 只能停用 `.output`，不可停用 `.pi-subagents` 歷史。
+- durable transcript 必須涵蓋 Agent tool、foreground/background、scheduler、cross-extension RPC 與 Workflow child 所有 manager spawn path。
+- transcript 必須逐步保存 user prompt、assistant partial text、tool call、tool result/error、steering message、compaction 前後可恢復內容與終止狀態。
+- checkpoint 必須在 spawn/queued、session 建立、turn/compaction、stop/abort/error/completion/shutdown 等關鍵時點更新；重新啟動時 running/queued checkpoint 若有 transcript，一律還原為可開啟的 `stopped` partial record。
+- `/agents` 與 ConversationViewer 必須把 `stopped`、`aborted`、`error`、`steered` 等終止狀態顯示清楚，歷史可重新開啟且 read-only。
+
+## 設計決策
+
+1. **事件管理採上游協定，資料層採 fork durable history。** `pi.events` 只負責 lifecycle/RPC 通知與跨 extension 協調；`.pi-subagents` 保存完整可解釋過程，兩者不互相取代。
+2. **歷史附掛下沉至 `AgentManager.spawn()`。** 不再只由 Agent tool 的 `attachTranscript()` 建立歷史；manager 在 caller callback 前確保 project-local transcript 已建立並寫入 initial user entry，因此 scheduler、RPC、Workflow child 也不會漏記。
+3. **輸出與歷史分離。** `record.outputFile` 仍受 `output_transcript` 控制；`record.historyFile`／`record.transcriptPath` 永遠建立（若檔案系統失敗，checkpoint 仍保存 metadata 並以 warning 呈現）。streamer 同時寫入兩個檔案時必須去重。
+4. **終止狀態不是刪除。** abort/stop 先停止 session、flush transcript、寫 checkpoint，再釋放 live handle；TTL 只釋放 session，不刪除有 `transcriptPath` 的 record。清理與 session shutdown 不得讓已寫入的歷史消失。
+5. **Workflow child 的生命週期由 Workflow 管理，但 manager 仍是歷史附掛的單一 seam。** Workflow 事件可維持上游的 hidden child 語義；`.pi-subagents` 以 child id 保存每個 worker 的工具與結果，Workflow journal 另外保存 orchestration progress。
+6. **UI 閃動採上游 render-cost bound 加 fork 的 deferred/coalesced refresh。** 不引入第二個 overlay，也不讓 spinner/timer 直接重建整個 viewer；只在有效 session change 時 invalidate/requestRender，並以 render key/cache 保持穩定行數。
+7. **套件身份與相容性不盲目照搬。** 保留 `@esso0428/pi-subagents`、JSON override 與 pi `>=0.80.8` peer floor；只在 typecheck/test 證明 API 必須提高時才調整。
+
+## 驗收條件
+
+- upstream Workflow 文件、實作、examples、tests 均可在 fork 中使用，且與 JSON override / existing Agents UI 共存。
+- RPC `consume` 可抑制重複 completion notification；RPC spawn/stop/ready/failed 流程有測試。
+- 各 spawn path 的 `.pi-subagents` transcript 都存在；在 tool call 尚未完成時 stop/abort，重新開啟仍可看到 prompt、tool call、tool result/error 與 partial assistant output。
+- turn limit、provider failure、父 signal abort、session shutdown、SIGKILL 後的 checkpoint restore 都標成 stopped/aborted/error/partial，而不是消失或誤報 completed。
+- ConversationViewer 仍保有 scrollbar rail、`[preview] [Esc]`、`w` 同一路徑與 in-place Tool Preview，並有 render cost regression coverage。
+- 通過 lint、typecheck、完整 unit、E2E、build、pack；版本更新、commit、push、publish 後以 GitHub 與 npm 狀態獨立確認。
+
+## 不在本次範圍
+
+- 不刪除 fork 的 durable history/recovery 模組來追上游檔案布局。
+- 不把上游 package name、作者、README branding 或 peer floor 直接覆蓋到 fork。
+- 不以「有 output transcript」替代 `.pi-subagents` durable history。
+- 不把 UI flicker 宣稱為上游已完全解決；上游 0.19.0 的 3d91023 是 render cost bound，仍需以 fork regression test 驗證實際事件序列。