@heyhuynhgiabuu/pi-task 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to `@heyhuynhgiabuu/pi-task` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] — 2026-06-25
+
+### Changed
+
+- **Modular refactor of `src/`.** The single-file `index.ts` is now a thin
+  wiring layer; the implementation is split across focused modules:
+  - `src/tool/` — `renderCall`, `renderResult`, `taskComplete`, `prompt`,
+    `schema`.
+  - `src/lifecycle/` — `polling`, `completion`, `toolStats`, `widget`,
+    `restore`.
+  - `src/subagent/` — `buildArgv`, `runSdk`, `tmux`, `waitCompletion`.
+  - `src/conversation.ts` — `findJsonlSessionByName`, registry and
+    `task-session-history` helpers.
+  - `src/constants.ts` — `BACKGROUND_CHECK_MS`, `COUNT_POLL_MS`,
+    `TASK_TIMEOUT_MS`, `MAX_POLL_ERRORS`.
+  - `src/types.ts` — `BackgroundTask`, `RegistryEntry`,
+    `TaskSessionHistoryEntry`, `TaskDetails`.
+- **Session JSONL is now the single source of truth for task results.**
+  `RESULT.md` is no longer read for completion detection or result text —
+  the final assistant message in `~/.pi/agent/sessions/.../<id>.jsonl`
+  is the authoritative result. This removes mid-write `EACCES` and
+  "stale truncated `RESULT.md`" failure modes entirely.
+- **Completion detection is gated on `stopReason`.** `hasAgentFinished()`
+  in `src/session-text.ts` only treats an assistant message as final when
+  its `stopReason` is `stop`, `endTurn`, `length`, `error`, or `aborted`.
+  `toolUse` mid-turn streaming text is correctly ignored.
+- **Background polling is hardened.**
+  - `checkInFlight` guard prevents overlapping poll ticks (no more
+    double-completion races on the `backgroundTasks` map).
+  - `MAX_POLL_ERRORS = 3` per-task counter absorbs transient filesystem
+    errors; a single rejected `readFile` no longer orphans a task.
+  - Try/catch around `checkTaskCompletion()` keeps the interval alive on
+    one-off failures.
+- **Reordered completion check flow.** Session JSONL is consulted before
+  pane liveness, so `remain-on-exit` panes no longer block detection.
+
+### Added
+
+- `renderCall` / `renderResult` / task-complete renderers with **Ctrl+O
+  expand/collapse** (via `keyHint("app.tools.expand")`) on the `task`
+  tool. Foreground results show stats + preview; expanded shows the full
+  result text. The keybinding hint falls back to `Ctrl+O` if the
+  `app.tools.expand` keybinding is not registered.
+- **Foreground real-time tool-call progress.** The foreground `execute`
+  path now polls the session file and emits `_onUpdate` callbacks while
+  waiting, so the parent pane shows a live `${n} tool calls` count
+  alongside the spawned subagent pane.
+
+### Fixed
+
+- The "scout - Description" / "scout — Description" duplicate header in
+  foreground results: `renderResult` no longer re-renders the header
+  that `renderCall` already rendered.
+- The `( to expand)` empty-keybinding hint: now falls back to a plain
+  `Ctrl+O to expand` label when `keyText("app.tools.expand")` is empty.
+
+### Verified
+
+- `npm run typecheck` passes
+- `npm run build` passes
+- `npm run smoke` passes
+- `npm pack --dry-run` succeeds
+
 ## [0.1.6] — 2026-06-25
 
 ### Changed
@@ -164,6 +227,7 @@ See the git history: `git log --oneline -- CHANGELOG.md`.
     [0.1.1]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.1
     [0.1.4]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.4
     [0.1.5]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.5
-    [0.1.6]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.6
-    [Keep a Changelog]: https://keepachangelog.com/
-    [Semantic Versioning]: https://semver.org/
+  [0.2.0]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.2.0
+  [0.1.6]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.6
+  [Keep a Changelog]: https://keepachangelog.com/
+  [Semantic Versioning]: https://semver.org/

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const BACKGROUND_CHECK_MS = 10000;
+export declare const COUNT_POLL_MS = 3000;
+export declare const TASK_TIMEOUT_MS: number;
+export declare const MAX_POLL_ERRORS = 3;

package/dist/constants.js

@@ -0,0 +1,4 @@
+export const BACKGROUND_CHECK_MS = 10_000; // poll every 10 sec
+export const COUNT_POLL_MS = 3_000; // update toolcall counts every 3 sec
+export const TASK_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
+export const MAX_POLL_ERRORS = 3; // consecutive poll failures before giving up on a task

package/dist/conversation.d.ts

@@ -1,3 +1,4 @@
+import type { RegistryEntry, TaskSessionHistoryEntry } from "./types.js";
 /**
  * Conversational subagent helpers.
  *
@@ -31,6 +32,13 @@ export type TaskSessionsRegistry = Record<string, {
 }>;
 export declare function getTasksFilePath(piDir: string): string;
 export declare function getTaskSessionsRegistryPath(piDir: string): string;
+export declare function readRegistry(piDir: string): RegistryEntry[];
+export declare function writeRegistry(piDir: string, entries: RegistryEntry[]): void;
+export declare function readTaskSessionHistory(piDir: string): TaskSessionHistoryEntry[];
+export declare function writeTaskSessionHistory(piDir: string, entries: TaskSessionHistoryEntry[]): void;
+export declare function upsertTaskSessionHistory(piDir: string, entry: TaskSessionHistoryEntry): void;
+export declare function findTaskSessionHistory(piDir: string, idOrSessionName: string): TaskSessionHistoryEntry | undefined;
+export declare function findJsonlSessionByName(piDir: string, sessionName: string, agentType: string): TaskSessionHistoryEntry | undefined;
 export declare function normalizeConversationId(value: unknown): string | undefined;
 export declare function readTaskSessionsRegistry(piDir: string): TaskSessionsRegistry;
 export declare function writeTaskSessionsRegistry(piDir: string, registry: TaskSessionsRegistry): void;

package/dist/conversation.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 /**
  * Conversational subagent helpers.
@@ -24,6 +24,101 @@ export function getTasksFilePath(piDir) {
 export function getTaskSessionsRegistryPath(piDir) {
     return join(piDir, "artifacts", TASK_SESSIONS_REGISTRY_FILE);
 }
+export function readRegistry(piDir) {
+    const path = join(piDir, "task-registry.json");
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function writeRegistry(piDir, entries) {
+    const path = join(piDir, "task-registry.json");
+    writeFileSync(path, JSON.stringify(entries, null, 2), "utf-8");
+}
+export function readTaskSessionHistory(piDir) {
+    const path = join(piDir, "task-session-history.json");
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function writeTaskSessionHistory(piDir, entries) {
+    const path = join(piDir, "task-session-history.json");
+    writeFileSync(path, JSON.stringify(entries, null, 2), "utf-8");
+}
+export function upsertTaskSessionHistory(piDir, entry) {
+    const entries = readTaskSessionHistory(piDir);
+    const index = entries.findIndex((existing) => existing.id === entry.id);
+    if (index >= 0) {
+        entries[index] = { ...entries[index], ...entry };
+    }
+    else {
+        entries.push(entry);
+    }
+    writeTaskSessionHistory(piDir, entries);
+}
+export function findTaskSessionHistory(piDir, idOrSessionName) {
+    return readTaskSessionHistory(piDir).find((entry) => entry.id === idOrSessionName || entry.sessionName === idOrSessionName);
+}
+export function findJsonlSessionByName(piDir, sessionName, agentType) {
+    const artifactsDir = join(piDir, "artifacts");
+    const sessionDir = join(artifactsDir, "sessions");
+    try {
+        if (!existsSync(sessionDir))
+            return undefined;
+        const files = readdirSync(sessionDir)
+            .filter((file) => file.endsWith(".jsonl"))
+            .sort()
+            .reverse();
+        for (const file of files) {
+            const content = readFileSync(join(sessionDir, file), "utf-8");
+            let startedAt = Date.now();
+            for (const rawLine of content.split("\n")) {
+                const line = rawLine.trim();
+                if (!line)
+                    continue;
+                try {
+                    const entry = JSON.parse(line);
+                    if (entry.type === "session" && entry.timestamp) {
+                        const parsed = Date.parse(entry.timestamp);
+                        if (Number.isFinite(parsed))
+                            startedAt = parsed;
+                    }
+                    if (entry.type === "session_info") {
+                        const name = entry.name ?? entry.session_info?.name;
+                        if (name === sessionName) {
+                            return {
+                                id: sessionName,
+                                agentType,
+                                description: `Resumed session ${sessionName}`,
+                                sessionName,
+                                sessionRef: join(sessionDir, file),
+                                startedAt,
+                                piDir,
+                                dir: artifactsDir,
+                                conversationId: sessionName,
+                                status: "done",
+                                background: false,
+                            };
+                        }
+                        break;
+                    }
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
 export function normalizeConversationId(value) {
     if (typeof value !== "string")
         return undefined;

package/dist/helpers.d.ts

@@ -40,8 +40,8 @@ export interface ToolCallRecord {
     id: string;
 }
 export declare const TASK_BACKGROUND_DEFAULT = true;
-export declare const TASK_RESULT_XML_INSTRUCTIONS = "<status>success|failure|blocked|partial</status>\n<summary>One sentence: what was accomplished</summary>\n<findings>Key findings with file:line references</findings>\n<evidence>Verification evidence, commands run, output snippets</evidence>\n<confidence>high|medium|low (optional \u2014 how certain the findings are)</confidence>\n<files>Comma-separated absolute paths of files read/created (optional)</files>\n\nPrefer writing this block to RESULT.md when done. If you cannot write the file, your final assistant message MUST include the same XML block.";
-export declare const OUTPUT_FORMAT_GUIDE = "<status>success|failure|blocked|partial</status>\n<summary>One sentence: what was accomplished</summary>\n<findings>Key findings with file:line references</findings>\n<evidence>Verification evidence, commands run, output snippets</evidence>\n<confidence>high|medium|low (optional \u2014 how certain the findings are)</confidence>\n<files>Comma-separated absolute paths of files read/created (optional)</files>\n\nPrefer writing this block to RESULT.md when done. If you cannot write the file, your final assistant message MUST include the same XML block.";
+export declare const TASK_PROMPT_INSTRUCTIONS = "Your final assistant message IS the result the parent agent will read.\n\nWhen you are done, end your final assistant message with a clear, self-contained summary in plain text. Do not wrap it in XML tags. Do not write a RESULT.md file \u2014 the parent agent reads your final assistant message from the session JSONL, not from any file.";
+export declare const OUTPUT_FORMAT_GUIDE = "Your final assistant message IS the result the parent agent will read.\n\nWhen you are done, end your final assistant message with a clear, self-contained summary in plain text. Do not wrap it in XML tags. Do not write a RESULT.md file \u2014 the parent agent reads your final assistant message from the session JSONL, not from any file.";
 export declare const TASK_TOOL_DESCRIPTION = "Launch a new agent to handle complex, multistep tasks autonomously.\n\nInclude relevant context from your current work in the prompt parameter \u2014\nthis becomes the subagent's instructions. The subagent knows nothing about what you've been doing except what you put in the prompt.\n\nWhen NOT to use:\n- To read a specific file path, use Read or Grep instead\n- To search for a class definition like 'class Foo', use Grep instead\n- To search code within 2-3 files, use Read instead\n- If no available agent fits the task, use other tools directly\n\nUsage notes:\n1. Provide complete context in the prompt \u2014 the subagent starts with a fresh context\n2. Launch multiple agents concurrently when possible (use a single message with multiple tool calls)\n3. Once you delegate work, do NOT duplicate it. Continue with non-overlapping tasks, or wait for the result\n4. Background is the default. Use background:false only when you need the caller to wait inline for the tmux task result\n5. Do not trust delegated output blindly. Read changed files, review the diff, verify scope, and run the relevant checks before claiming completion\n6. Clearly tell the agent whether to write code or just research, since it doesn't know the user's intent\n7. The result returned by the agent is not visible to the user. Send a concise summary back to the user\n8. Pass task_id to resume a previous subagent session (continues with its prior context)\n\nBackground mode (background: true):\n- Launches the subagent asynchronously and returns immediately\n- You will be notified automatically when it finishes\n- DO NOT sleep, poll, ask the task for status, or duplicate its work while it runs in background\n- Avoid working with the same files or topics the background task is using\n- Work on non-overlapping tasks, or briefly tell the user what you launched and end your response";
 /** @deprecated Import from ./agent-tools.js */
 export { ALL_TOOL_NAMES, BUILTIN_TOOL_NAMES } from "./agent-tools.js";

package/dist/helpers.js

@@ -32,15 +32,10 @@ export function parseMarkdownFrontmatter(content) {
 }
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const TASK_BACKGROUND_DEFAULT = true;
-export const TASK_RESULT_XML_INSTRUCTIONS = `<status>success|failure|blocked|partial</status>
-<summary>One sentence: what was accomplished</summary>
-<findings>Key findings with file:line references</findings>
-<evidence>Verification evidence, commands run, output snippets</evidence>
-<confidence>high|medium|low (optional — how certain the findings are)</confidence>
-<files>Comma-separated absolute paths of files read/created (optional)</files>
+export const TASK_PROMPT_INSTRUCTIONS = `Your final assistant message IS the result the parent agent will read.
 
-Prefer writing this block to RESULT.md when done. If you cannot write the file, your final assistant message MUST include the same XML block.`;
-export const OUTPUT_FORMAT_GUIDE = TASK_RESULT_XML_INSTRUCTIONS;
+When you are done, end your final assistant message with a clear, self-contained summary in plain text. Do not wrap it in XML tags. Do not write a RESULT.md file — the parent agent reads your final assistant message from the session JSONL, not from any file.`;
+export const OUTPUT_FORMAT_GUIDE = TASK_PROMPT_INSTRUCTIONS;
 export const TASK_TOOL_DESCRIPTION = `Launch a new agent to handle complex, multistep tasks autonomously.
 
 Include relevant context from your current work in the prompt parameter —
@@ -89,7 +84,7 @@ export function parseResultXml(raw) {
         !extractTag(raw, EVIDENCE_RE)) {
         return {
             status: "unknown",
-            summary: raw.slice(0, 500),
+            summary: raw.trim(),
             findings: "",
             evidence: "",
             confidence: "",

package/dist/index.d.ts

@@ -1,35 +1,18 @@
 /**
  * Task Tool — Delegate complex work to specialist agents.
  *
- * Spawns pi CLI in a tmux split pane (so you can watch it live) and
- * detects completion via RESULT.md polling. On completion, tool call
- * count and duration are reported as a notification.
+ * Spawns pi CLI in a tmux split pane (foreground) or background.
+ * Completion is detected from the subagent's final assistant message
+ * in the persistent session JSONL (stopReason gating). The final message
+ * is the authoritative result; no RESULT.md is used.
  *
  * Three agent sources:
  *   - .pi/agents/*.md        project-local agents
  *   - ~/.pi/agent/agents/*.md user-global agents (fallback)
  *
  * P0: Persistent task registry (appendEntry + JSON), --session resume,
- *     sendMessage completion notification.
- * P1: Foreground mode (background:false, inline subprocess), pane death
- *     detection, 30-minute timeout.
+ *     sendMessage completion notification, Ctrl+O expand/collapse.
+ * P1: Foreground mode (background:false), pane death detection, timeout.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-export /** Details attached to tool result for rendering. */ interface TaskDetails {
-    task_id: string;
-    agent_type: string;
-    description: string;
-    conversation_id?: string;
-    phase: "done" | "timeout" | "aborted" | "failed";
-    status?: string;
-    summary?: string;
-    findings?: string;
-    evidence?: string;
-    confidence?: string;
-    duration_ms?: number;
-    turn_count?: number;
-    tool_uses?: number;
-    background?: boolean;
-    tmux_session?: string;
-}
 export default function (pi: ExtensionAPI): void;