@heyhuynhgiabuu/pi-task 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,51 @@ 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.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 +121,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 +161,9 @@ 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.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

@@ -45,7 +45,7 @@ Foreground task:
 
 Background task:
 
-```json
+```
 {
   "agent_type": "scout",
   "description": "Research SDK docs",
@@ -54,6 +54,38 @@ Background task:
 }
 ```
 
+Durable specialist conversation:
+
+```
+{
+  "agent_type": "scout",
+  "conversation_id": "research-ai",
+  "description": "Ask research assistant",
+  "background": false,
+  "prompt": "Continue our prior research thread. What did we conclude about retrieval evaluation?"
+}
+```
+
+        `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 (all flat at the top of `.pi/artifacts/`, no
+        per-task subdirs):
+
+        ```
+        .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.
+
 ## Agent precedence
 
 When two agents have the same name, later sources override earlier ones:

package/dist/conversation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Conversational subagent helpers.
+ *
+ * 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;
+    agent_type: string;
+    session_file: string;
+    created_at: string;
+    last_used_at: string;
+    last_prompt?: 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 normalizeConversationId(value: unknown): string | undefined;
+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;
+    sessionFile: string;
+    prompt: string;
+    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;

package/dist/conversation.js

@@ -0,0 +1,238 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Conversational subagent helpers.
+ *
+ * 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 const TASKS_FILE = "TASKS.md";
+export const TASK_SESSIONS_REGISTRY_FILE = "task-sessions.json";
+export function getTasksFilePath(piDir) {
+    return join(piDir, "artifacts", TASKS_FILE);
+}
+export function getTaskSessionsRegistryPath(piDir) {
+    return join(piDir, "artifacts", TASK_SESSIONS_REGISTRY_FILE);
+}
+export function normalizeConversationId(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const conversationId = value.trim();
+    if (!conversationId)
+        return undefined;
+    if (!/^[A-Za-z0-9._-]{1,80}$/.test(conversationId)) {
+        throw new Error("conversation_id must be 1-80 chars and contain only letters, numbers, '.', '_' or '-'");
+    }
+    return conversationId;
+}
+export function readTaskSessionsRegistry(piDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(getTaskSessionsRegistryPath(piDir), "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
+        }
+        const registry = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (value &&
+                typeof value === "object" &&
+                typeof value.task_id === "string" &&
+                typeof value.session_file === "string") {
+                const v = value;
+                registry[key] = { task_id: v.task_id, session_file: v.session_file };
+            }
+        }
+        return registry;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeTaskSessionsRegistry(piDir, registry) {
+    mkdirSync(join(piDir, "artifacts"), { recursive: true });
+    writeFileSync(getTaskSessionsRegistryPath(piDir), `${JSON.stringify(registry, null, 2)}\n`, "utf-8");
+}
+/**
+ * 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 function readTaskBlock(piDir, taskId) {
+    let content;
+    try {
+        content = readFileSync(getTasksFilePath(piDir), "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    return parseTaskBlocks(content).get(taskId);
+}
+export function listTaskBlocks(piDir) {
+    let content;
+    try {
+        content = readFileSync(getTasksFilePath(piDir), "utf-8");
+    }
+    catch {
+        return new Map();
+    }
+    return parseTaskBlocks(content);
+}
+function parseTaskBlocks(content) {
+    const blocks = new Map();
+    const lines = content.split("\n");
+    let currentTaskId = null;
+    let currentStatus = null;
+    let currentBody = [];
+    const flush = () => {
+        if (currentTaskId !== null) {
+            blocks.set(currentTaskId, {
+                status: currentStatus,
+                body: currentBody.join("\n"),
+            });
+        }
+        currentTaskId = null;
+        currentStatus = null;
+        currentBody = [];
+    };
+    for (const line of lines) {
+        const heading = line.match(/^###\s+(\S+)\s*$/);
+        if (heading) {
+            flush();
+            currentTaskId = heading[1];
+            continue;
+        }
+        if (currentTaskId === null)
+            continue;
+        const statusMatch = line.match(/^status:\s*(\S+)/);
+        if (statusMatch) {
+            currentStatus = statusMatch[1].toLowerCase();
+            continue;
+        }
+        currentBody.push(line);
+    }
+    flush();
+    return blocks;
+}
+/**
+ * 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 function writeTaskBlock(options) {
+    const path = getTasksFilePath(options.piDir);
+    let content = "";
+    try {
+        content = readFileSync(path, "utf-8");
+        if (!content.endsWith("\n"))
+            content += "\n";
+    }
+    catch {
+        content = "";
+    }
+    const heading = `### ${options.taskId}`;
+    const statusLine = `status: ${options.status} | updated: ${options.updated}`;
+    const block = `${heading}\n${statusLine}\n\n${options.body}\n`;
+    const headingRe = new RegExp(`^### ${escapeRegExp(options.taskId)}\\s*$`, "m");
+    const match = content.match(headingRe);
+    if (match && match.index !== undefined) {
+        const start = match.index;
+        const after = content.slice(start);
+        const nextHeading = after.search(/^###\s+\S+/m);
+        const end = nextHeading > 0 ? start + nextHeading : content.length;
+        content = content.slice(0, start) + block + content.slice(end);
+    }
+    else {
+        if (content.length > 0 && !content.endsWith("\n\n")) {
+            content += "\n";
+        }
+        content += block;
+    }
+    mkdirSync(join(options.piDir, "artifacts"), { recursive: true });
+    writeFileSync(path, content, "utf-8");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function parseMetadataFromBody(body) {
+    if (!body)
+        return undefined;
+    const match = body.match(/```json\n([\s\S]*?)\n```/);
+    if (!match)
+        return undefined;
+    try {
+        return JSON.parse(match[1]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 function writeConversationArtifacts(input) {
+    const now = new Date().toISOString();
+    const existing = readTaskBlock(input.piDir, input.taskId);
+    const previous = parseMetadataFromBody(existing?.body);
+    const metadata = {
+        conversation_id: input.conversationId,
+        task_id: input.taskId,
+        agent_type: input.agentType,
+        session_file: input.sessionFile,
+        created_at: previous?.created_at ?? now,
+        last_used_at: now,
+        last_prompt: input.prompt,
+    };
+    const body = [
+        "#### Metadata",
+        "",
+        "```json",
+        JSON.stringify(metadata, null, 2),
+        "```",
+        "",
+        "#### Result",
+        "",
+        input.result.trim(),
+        "",
+    ].join("\n");
+    writeTaskBlock({
+        piDir: input.piDir,
+        taskId: input.taskId,
+        status: "done",
+        updated: now,
+        body,
+    });
+    const registry = readTaskSessionsRegistry(input.piDir);
+    registry[input.conversationId] = {
+        task_id: input.taskId,
+        session_file: input.sessionFile,
+    };
+    writeTaskSessionsRegistry(input.piDir, registry);
+    return metadata;
+}
+export function renderConversationSessions(piDir) {
+    const blocks = listTaskBlocks(piDir);
+    if (blocks.size === 0) {
+        return 'No durable task conversations found. Start one with task({ conversation_id: "research-ai", ... }).';
+    }
+    const entries = Array.from(blocks.entries()).sort(([a], [b]) => a.localeCompare(b));
+    const lines = ["Durable task conversations:"];
+    for (const [taskId, block] of entries) {
+        const metadata = parseMetadataFromBody(block.body);
+        const agent = metadata?.agent_type ?? "unknown";
+        const last = metadata?.last_used_at ?? "unknown";
+        const conv = metadata?.conversation_id ?? "(no conversation_id)";
+        lines.push(`${conv} -> ${taskId} — ${agent}, last used ${last}`);
+    }
+    return lines.join("\n");
+}

package/dist/helpers.d.ts

@@ -72,12 +72,12 @@ export declare function formatAgentList(agents: AgentConfig[]): string;
  * Build pi CLI arguments for spawning or resuming a sub-agent session.
  *
  * - Fresh spawn: omit `resume` or pass falsy — `--session` is not included.
- * - Resume: pass `resume=true` — `--session <name>` is included so pi
- *   continues the existing session file in --session-dir.
- */
-export declare function buildPiArgs(agent: AgentConfig, sessionName: string, sessionDir: string, promptContent: string, resume?: boolean, parentToolNames?: string[]): string[];
+     * - Resume: pass `resume=true` and optionally `resumeSessionRef` —
+     *   `--session <ref>` is included so pi continues an existing session.
+     */
+export declare function buildPiArgs(agent: AgentConfig, sessionName: string, sessionDir: string, promptContent: string, resume?: boolean, parentToolNames?: string[], resumeSessionRef?: string): string[];
 /** Count tool uses and turns from pi JSONL session files. */
-export declare function countToolUses(sessionDir: string): {
+export declare function countToolUses(sessionDir: string, sessionName?: string): {
     toolUses: number;
     turns: number;
 };
@@ -94,7 +94,7 @@ export declare function summarizeArgs(toolName: string, args: unknown): string;
  * Returns total counts plus the last `limit` records in chronological order.
  * Safe against malformed lines and missing fields.
  */
-export declare function readRecentToolCalls(sessionDir: string, limit?: number): {
+export declare function readRecentToolCalls(sessionDir: string, limit?: number, sessionName?: string): {
     toolUses: number;
     turns: number;
     recent: ToolCallRecord[];

package/dist/helpers.js

@@ -256,22 +256,42 @@ export function formatAgentList(agents) {
  * Build pi CLI arguments for spawning or resuming a sub-agent session.
  *
  * - Fresh spawn: omit `resume` or pass falsy — `--session` is not included.
- * - Resume: pass `resume=true` — `--session <name>` is included so pi
- *   continues the existing session file in --session-dir.
- */
-export function buildPiArgs(agent, sessionName, sessionDir, promptContent, resume, parentToolNames) {
+     * - Resume: pass `resume=true` and optionally `resumeSessionRef` —
+     *   `--session <ref>` is included so pi continues an existing session.
+     */
+export function buildPiArgs(agent, sessionName, sessionDir, promptContent, resume, parentToolNames, resumeSessionRef) {
     return buildPiArgv({
         agent,
         sessionName,
         sessionDir,
         promptContent,
         resume,
+        resumeSessionRef,
         parentToolNames,
     });
 }
 // ─── JSONL Session Helpers ───────────────────────────────────────────────────
+function matchesJsonlSessionName(content, sessionName) {
+    if (!sessionName)
+        return true;
+    for (const rawLine of content.split("\n")) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (entry.type === "session_info") {
+                return (entry.name ?? entry.session_info?.name) === sessionName;
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return false;
+}
 /** Count tool uses and turns from pi JSONL session files. */
-export function countToolUses(sessionDir) {
+export function countToolUses(sessionDir, sessionName) {
     let toolUses = 0;
     let turns = 0;
     try {
@@ -280,6 +300,8 @@ export function countToolUses(sessionDir) {
         const files = readdirSync(sessionDir).filter((f) => f.endsWith(".jsonl"));
         for (const file of files) {
             const content = readFileSync(join(sessionDir, file), "utf-8");
+            if (!matchesJsonlSessionName(content, sessionName))
+                continue;
             for (const rawLine of content.split("\n")) {
                 const line = rawLine.trim();
                 if (!line)
@@ -368,7 +390,7 @@ export function summarizeArgs(toolName, args) {
  * Returns total counts plus the last `limit` records in chronological order.
  * Safe against malformed lines and missing fields.
  */
-export function readRecentToolCalls(sessionDir, limit = 12) {
+export function readRecentToolCalls(sessionDir, limit = 12, sessionName) {
     let toolUses = 0;
     let turns = 0;
     const calls = [];
@@ -379,6 +401,8 @@ export function readRecentToolCalls(sessionDir, limit = 12) {
         const files = readdirSync(sessionDir).filter((f) => f.endsWith(".jsonl"));
         for (const file of files) {
             const content = readFileSync(join(sessionDir, file), "utf-8");
+            if (!matchesJsonlSessionName(content, sessionName))
+                continue;
             for (const rawLine of content.split("\n")) {
                 const line = rawLine.trim();
                 if (!line)

package/dist/index.d.ts

@@ -15,4 +15,21 @@
  *     detection, 30-minute 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;