@heyhuynhgiabuu/pi-task 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,114 @@ 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
+
+- Per-task data is now in flat files at the top of `.pi/artifacts/`.
+  No per-task subdirs, no `<task-id>` paths. The pikit canonical
+  files (TODO.md, PLAN.md, PROGRESS.md, DECISIONS.md) are flat at the
+  same level; pi-task files now sit alongside them.
+- Refined the task TUI widget and background completion rendering:
+  foreground/background task stats now use consistent colors, background
+  completion summaries use a padded themed result block, completed
+  background widgets no longer duplicate the main-pane completion, and
+  final tool-call counts now match the live widget count.
+
+### Layout
+
+- `.pi/artifacts/TASKS.md` — one `### <task-id>` block per task, with
+  H4 subsections for `#### Metadata` (JSON) and `#### Result`.
+- `.pi/artifacts/task-sessions.json` — registry mapping
+  `conversation_id` to `{ task_id, session_file }`. Renamed from
+  the v0.1.5 `task-conversations.json`.
+- The subagent's session is auto-saved by pi at
+  `~/.pi/agent/sessions/<cwd>/<session-id>.jsonl`. pi-task reads
+  the last assistant message from there to populate `#### Result`
+  in `TASKS.md`. The subagent's final assistant message IS the
+  result; no separate result file is required.
+
+### Removed
+
+- `.pi/artifacts/task-<id>/` per-task subdirs (and the
+  `metadata.json` + `SESSION.md` + `sessions/` files inside them).
+  All per-task data lives in `TASKS.md` blocks now.
+- `.pi/artifacts/task-conversations.json` — replaced by
+  `task-sessions.json`.
+- The `taskArtifactName(taskId)` / `taskIdFromArtifactName(name)`
+  helpers and the `getArtifactsDir(piDir)` / `getTaskDir(piDir)` /
+  `getTaskRunsDir(piDir)` helpers.
+
+### Verified
+
+- `npm test` passes
+- `npm run typecheck` passes
+- `npm run build` passes
+- `npm run smoke` passes
+
 ## [0.1.4] — 2026-06-21
 
 ### Fixed
@@ -76,7 +184,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - `npm view @heyhuynhgiabuu/pi-task@0.1.2 pi` returns
   `{ extensions: [ './dist/index.js' ] }`
 
-[0.1.2]: https://github.com/buddingnewinsights/pi-task/releases/tag/v0.1.2
+  [0.1.2]: https://github.com/heyhuynhgiabuu/pi-task/releases/tag/v0.1.2
 
 ## [0.1.1] — 2025
 
@@ -116,6 +224,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 See the git history: `git log --oneline -- CHANGELOG.md`.
 
-[0.1.1]: https://github.com/buddingnewinsights/pi-task/releases/tag/v0.1.1
-[Keep a Changelog]: https://keepachangelog.com/
-[Semantic Versioning]: https://semver.org/
+    [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.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/README.md

@@ -66,20 +66,25 @@ Durable specialist conversation:
 }
 ```
 
-`conversation_id` maps to one existing `task-<id>` artifact under `.pi/artifacts/` and reuses its `sessions/` directory on later calls. This is for scoped specialist memory, e.g. a reusable research assistant. Use `/task-sessions` to list known durable conversations.
+        `conversation_id` maps to a durable subagent run. Reused across calls
+        to keep specialist memory, e.g. a reusable research assistant.
+        Use `/task-sessions` to list known durable conversations.
 
-Stored files:
+        Stored files (all flat at the top of `.pi/artifacts/`, no
+        per-task subdirs):
 
-```
-.pi/artifacts/task-registry.json
-.pi/artifacts/task-<id>/CONTEXT.md
-.pi/artifacts/task-<id>/RESULT.md
-.pi/artifacts/task-<id>/SESSION.md
-.pi/artifacts/task-<id>/metadata.json
-.pi/artifacts/task-<id>/sessions/
-```
+        ```
+        .pi/artifacts/TASKS.md              # one ### <task-id> block per task
+        .pi/artifacts/task-sessions.json    # conversation_id -> { task_id, session_file }
+        ```
+
+        The subagent's session is auto-saved by pi at
+        `~/.pi/agent/sessions/<cwd>/<session-id>.jsonl`. pi-task reads
+        the last assistant message from there to populate
+        `#### Result` in `TASKS.md`. The subagent's final message IS
+        the result; no separate result file is required.
 
-Note: true conversation resume requires the tmux/CLI backend so Pi can reopen the saved subagent session. SDK fallback can run one-shot tasks, but it cannot resume a prior Pi session.
+    Note: true conversation resume requires the tmux/CLI backend so Pi can reopen the saved subagent session. SDK fallback can run one-shot tasks, but it cannot resume a prior Pi session.
 
 ## Agent precedence
 

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,39 +1,94 @@
+import type { RegistryEntry, TaskSessionHistoryEntry } from "./types.js";
 /**
  * Conversational subagent helpers.
  *
- * Durable subagent conversations reuse the existing
- * `.pi/artifacts/task-<id>/` artifact convention and add a small
- * `conversation_id` -> `task-<id>` registry under the same artifacts dir.
+ * Per-task data lives in `.pi/artifacts/TASKS.md` as `### <task-id>` blocks.
+ * A small `task-sessions.json` registry in the same directory maps
+ * `conversation_id` to the auto-saved session file path so the
+ * subagent can be resumed later.
+ *
+ * The subagent's session is auto-saved by pi at
+ * `~/.pi/agent/sessions/<cwd>/<session-id>.jsonl`. pi-task does not
+ * maintain its own session storage.
+ *
+ * All artifacts live flat at the top of `.pi/artifacts/`, alongside the
+ * pikit canonical files (TODO.md, PLAN.md, PROGRESS.md, DECISIONS.md).
+ * No subdirs. No per-task paths.
  */
+export declare const TASKS_FILE = "TASKS.md";
+export declare const TASK_SESSIONS_REGISTRY_FILE = "task-sessions.json";
 export interface ConversationMetadata {
     conversation_id: string;
     task_id: string;
-    artifact: string;
     agent_type: string;
-    session_dir: string;
-    session_name: string;
+    session_file: string;
     created_at: string;
     last_used_at: string;
     last_prompt?: string;
 }
-export type ConversationRegistry = Record<string, string>;
-export declare const CONVERSATION_REGISTRY_FILE = "task-conversations.json";
-export declare function getArtifactsDir(piDir: string): string;
-export declare function getConversationRegistryPath(piDir: string): string;
-export declare function taskArtifactName(taskId: string): string;
-export declare function taskIdFromArtifactName(artifactName: string): string;
+export type TaskSessionsRegistry = Record<string, {
+    task_id: string;
+    session_file: 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 readConversationRegistry(piDir: string): ConversationRegistry;
-export declare function writeConversationRegistry(piDir: string, registry: ConversationRegistry): void;
-export declare function readConversationMetadata(metadataPath: string): ConversationMetadata | undefined;
-export declare function buildSessionCard(metadata: ConversationMetadata): string;
-export declare function writeConversationArtifacts(options: {
-    taskDir: string;
+export declare function readTaskSessionsRegistry(piDir: string): TaskSessionsRegistry;
+export declare function writeTaskSessionsRegistry(piDir: string, registry: TaskSessionsRegistry): void;
+/**
+ * Find a `### <task-id>` block in TASKS.md. Returns the block content
+ * (everything between the heading and the next H3 or EOF) plus the
+ * status line if present. Returns undefined if no block exists.
+ */
+export declare function readTaskBlock(piDir: string, taskId: string): {
+    status: string | null;
+    body: string;
+} | undefined;
+export declare function listTaskBlocks(piDir: string): Map<string, {
+    status: string | null;
+    body: string;
+}>;
+/**
+ * Append or update a `### <task-id>` block in TASKS.md. If the block
+ * already exists, its body is replaced. Otherwise, the block is
+ * appended at the end of the file.
+ */
+export declare function writeTaskBlock(options: {
+    piDir: string;
+    taskId: string;
+    status: "active" | "done" | "abandoned";
+    updated: string;
+    body: string;
+}): void;
+export declare function parseMetadataFromBody(body: string | undefined): {
+    created_at?: string;
+    last_used_at?: string;
+    agent_type?: string;
+    session_file?: string;
+    conversation_id?: string;
+    last_prompt?: string;
+} | undefined;
+export interface WriteTaskBlockInput {
+    piDir: string;
     taskId: string;
     conversationId: string;
     agentType: string;
-    sessionDir: string;
-    sessionName: string;
+    sessionFile: string;
     prompt: string;
-}): ConversationMetadata;
+    result: string;
+    resultLabel?: string;
+}
+/**
+ * Persist a completed task: write (or update) the `### <task-id>` block
+ * in TASKS.md with metadata and result as H4 subsections. Also updates
+ * the task-sessions registry.
+ */
+export declare function writeConversationArtifacts(input: WriteTaskBlockInput): ConversationMetadata;
 export declare function renderConversationSessions(piDir: string): string;