@heyhuynhgiabuu/pi-task 0.1.4 → 0.1.5

package/README.md

@@ -45,7 +45,7 @@ Foreground task:
 
 Background task:
 
-```json
+```
 {
   "agent_type": "scout",
   "description": "Research SDK docs",
@@ -54,6 +54,33 @@ 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 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.
+
+Stored files:
+
+```
+.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/
+```
+
+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,39 @@
+/**
+ * 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.
+ */
+export interface ConversationMetadata {
+    conversation_id: string;
+    task_id: string;
+    artifact: string;
+    agent_type: string;
+    session_dir: string;
+    session_name: 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 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;
+    taskId: string;
+    conversationId: string;
+    agentType: string;
+    sessionDir: string;
+    sessionName: string;
+    prompt: string;
+}): ConversationMetadata;
+export declare function renderConversationSessions(piDir: string): string;

package/dist/conversation.js

@@ -0,0 +1,123 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const CONVERSATION_REGISTRY_FILE = "task-conversations.json";
+export function getArtifactsDir(piDir) {
+    return join(piDir, "artifacts");
+}
+export function getConversationRegistryPath(piDir) {
+    return join(getArtifactsDir(piDir), CONVERSATION_REGISTRY_FILE);
+}
+export function taskArtifactName(taskId) {
+    return taskId.startsWith("task-") ? taskId : `task-${taskId}`;
+}
+export function taskIdFromArtifactName(artifactName) {
+    return artifactName.startsWith("task-")
+        ? artifactName.slice("task-".length)
+        : artifactName;
+}
+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 readConversationRegistry(piDir) {
+    try {
+        const parsed = JSON.parse(readFileSync(getConversationRegistryPath(piDir), "utf-8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
+        }
+        const registry = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === "string")
+                registry[key] = value;
+        }
+        return registry;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConversationRegistry(piDir, registry) {
+    const artifactsDir = getArtifactsDir(piDir);
+    mkdirSync(artifactsDir, { recursive: true });
+    writeFileSync(getConversationRegistryPath(piDir), `${JSON.stringify(registry, null, 2)}\n`, "utf-8");
+}
+export function readConversationMetadata(metadataPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(metadataPath, "utf-8"));
+        if (!parsed.conversation_id || !parsed.task_id)
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function buildSessionCard(metadata) {
+    return [
+        `# ${metadata.conversation_id}`,
+        "",
+        `Agent: ${metadata.agent_type}`,
+        `Task: ${taskArtifactName(metadata.task_id)}`,
+        `Last used: ${metadata.last_used_at}`,
+        `Session dir: ${metadata.session_dir}`,
+        "",
+        "## Resume",
+        "",
+        "```json",
+        JSON.stringify({
+            agent_type: metadata.agent_type,
+            conversation_id: metadata.conversation_id,
+            prompt: "Continue from the prior specialist conversation.",
+        }, null, 2),
+        "```",
+        "",
+        "## Last prompt",
+        "",
+        metadata.last_prompt ?? "",
+        "",
+    ].join("\n");
+}
+export function writeConversationArtifacts(options) {
+    const now = new Date().toISOString();
+    const metadataPath = join(options.taskDir, "metadata.json");
+    const existing = readConversationMetadata(metadataPath);
+    const metadata = {
+        conversation_id: options.conversationId,
+        task_id: options.taskId,
+        artifact: taskArtifactName(options.taskId),
+        agent_type: options.agentType,
+        session_dir: options.sessionDir,
+        session_name: options.sessionName,
+        created_at: existing?.created_at ?? now,
+        last_used_at: now,
+        last_prompt: options.prompt,
+    };
+    mkdirSync(options.taskDir, { recursive: true });
+    writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
+    writeFileSync(join(options.taskDir, "SESSION.md"), buildSessionCard(metadata), "utf-8");
+    return metadata;
+}
+export function renderConversationSessions(piDir) {
+    const registry = readConversationRegistry(piDir);
+    const entries = Object.entries(registry).sort(([left], [right]) => left.localeCompare(right));
+    if (entries.length === 0) {
+        return 'No durable task conversations found. Start one with task({ conversation_id: "research-ai", ... }).';
+    }
+    const lines = ["Durable task conversations:"];
+    for (const [conversationId, artifactName] of entries) {
+        const taskId = taskIdFromArtifactName(artifactName);
+        const metadata = readConversationMetadata(join(getArtifactsDir(piDir), taskArtifactName(taskId), "metadata.json"));
+        const suffix = metadata
+            ? ` — ${metadata.agent_type}, last used ${metadata.last_used_at}`
+            : "";
+        lines.push(`${conversationId} -> ${taskArtifactName(taskId)}${suffix}`);
+    }
+    return lines.join("\n");
+}

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;

package/dist/index.js

@@ -21,6 +21,7 @@ import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "@sinclair/typebox";
+import { getArtifactsDir, normalizeConversationId, readConversationMetadata, readConversationRegistry, renderConversationSessions, taskArtifactName, taskIdFromArtifactName, writeConversationArtifacts, writeConversationRegistry, } from "./conversation.js";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { TASK_BACKGROUND_DEFAULT, TASK_RESULT_XML_INSTRUCTIONS, TASK_TOOL_DESCRIPTION, buildTmuxSplitWindowArgs, chooseTmuxSplitDirection, formatBackgroundReceipt, buildPiArgs, parseResultXml, formatMs, shellQuote, discoverAgents, formatAgentList, countToolUses, readRecentToolCalls, } from "./helpers.js";
 import { runSdkSubagent } from "./subagent/runSdk.js";
@@ -31,7 +32,7 @@ const BUNDLED_AGENT_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "a
 const BACKGROUND_CHECK_MS = 10_000; // poll every 10 sec
 const COUNT_POLL_MS = 3_000; // update toolcall counts every 3 sec
 const TASK_TIMEOUT_MS = 30 * 60 * 1_000; // 30 minutes
-// ─── Registry helpers (durable JSON) ─────────────────────────────────────────
+// Conversation helpers live in ./conversation.js.
 function readRegistry(piDir) {
     const path = join(piDir, "task-registry.json");
     try {
@@ -190,6 +191,7 @@ export default function (pi) {
             startedAt: entry.startedAt,
             toolUses: 0,
             turns: 0,
+            conversationId: entry.conversationId,
             recentCalls: [],
         };
         backgroundTasks.set(entry.id, bgtask);
@@ -478,7 +480,10 @@ export default function (pi) {
                 description: "A short (3-5 word) summary of the task",
             }),
             task_id: Type.Optional(Type.String({
-                description: "Resume a previous task by ID (continues the same subagent session with its prior context instead of creating a fresh one)",
+                description: "Resume an existing background task by id instead of starting a new task.",
+            })),
+            conversation_id: Type.Optional(Type.String({
+                description: "Durable specialist conversation id. Reuses .pi/artifacts/task-<id>/sessions when called again.",
             })),
             background: Type.Optional(Type.Boolean({
                 description: "Run in background (async). You will be notified when it completes. DO NOT sleep, poll, ask the task for status, or duplicate its work while it runs in background.",
@@ -508,13 +513,115 @@ export default function (pi) {
                     isError: true,
                 };
             }
-            // ── Resolve task identity: new or resume ───────────────────────────
+            // ── Resolve task identity: new, task resume, or conversation resume ──
+            const conversationId = normalizeConversationId(params.conversation_id);
+            const conversationRegistry = conversationId
+                ? readConversationRegistry(piDir)
+                : {};
+            const registeredArtifact = conversationId
+                ? conversationRegistry[conversationId]
+                : undefined;
+            const registeredTaskId = registeredArtifact
+                ? taskIdFromArtifactName(registeredArtifact)
+                : undefined;
+            if (params.task_id &&
+                registeredTaskId &&
+                params.task_id !== registeredTaskId) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `conversation_id "${conversationId}" maps to ${taskArtifactName(registeredTaskId)}, not ${taskArtifactName(params.task_id)}. Omit task_id or use the mapped task id.`,
+                        },
+                    ],
+                    details: {
+                        phase: "failed",
+                        error: "conversation_id/task_id mismatch",
+                    },
+                    isError: true,
+                };
+            }
             let id;
             let sessionName;
             let artifactDir;
             let resultPath;
             let resume = false;
-            if (params.task_id) {
+            if (registeredTaskId) {
+                id = registeredTaskId;
+                sessionName = taskArtifactName(id);
+                artifactDir = join(getArtifactsDir(piDir), sessionName);
+                resultPath = join(artifactDir, "RESULT.md");
+                if (!existsSync(artifactDir)) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `conversation_id "${conversationId}" points to missing artifact directory: ${artifactDir}`,
+                            },
+                        ],
+                        details: {
+                            phase: "failed",
+                            error: "Conversation artifact dir missing",
+                            conversation_id: conversationId,
+                        },
+                        isError: true,
+                    };
+                }
+                const metadata = readConversationMetadata(join(artifactDir, "metadata.json"));
+                if (metadata?.agent_type && metadata.agent_type !== agent.name) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `conversation_id "${conversationId}" belongs to agent "${metadata.agent_type}", not "${agent.name}". Use the original agent_type or start a different conversation_id.`,
+                            },
+                        ],
+                        details: {
+                            phase: "failed",
+                            error: "conversation_id agent_type mismatch",
+                            conversation_id: conversationId,
+                        },
+                        isError: true,
+                    };
+                }
+                resume = true;
+                const entry = readRegistry(piDir).find((candidate) => candidate.id === id);
+                if (params.background !== false &&
+                    entry?.paneId &&
+                    paneExists(entry.paneId)) {
+                    const bgtask = {
+                        dir: artifactDir,
+                        agentType: entry.agentType,
+                        sessionName,
+                        paneId: entry.paneId,
+                        originalPane: null,
+                        description: params.description || entry.description,
+                        startedAt: entry.startedAt,
+                        toolUses: 0,
+                        turns: 0,
+                        conversationId,
+                        recentCalls: [],
+                    };
+                    backgroundTasks.set(id, bgtask);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Resumed conversation "${conversationId}" via ${taskArtifactName(id)}. The subagent is running in background and will notify on completion.`,
+                            },
+                        ],
+                        details: {
+                            task_id: id,
+                            agent_type: agent.name,
+                            description: params.description,
+                            conversation_id: conversationId,
+                            tmux_session: sessionName,
+                            background: true,
+                        },
+                    };
+                }
+            }
+            else if (params.task_id) {
                 // Look up the task in the persistent registry
                 const entries = readRegistry(piDir);
                 const entry = entries.find((e) => e.id === params.task_id);
@@ -568,6 +675,7 @@ export default function (pi) {
                         startedAt: entry.startedAt,
                         toolUses: 0,
                         turns: 0,
+                        conversationId: entry.conversationId,
                         recentCalls: [],
                     };
                     backgroundTasks.set(id, bgtask);
@@ -582,6 +690,7 @@ export default function (pi) {
                             task_id: id,
                             agent_type: agent.name,
                             description: params.description,
+                            conversation_id: entry.conversationId ?? conversationId,
                             tmux_session: sessionName,
                             background: true,
                         },
@@ -590,11 +699,41 @@ export default function (pi) {
             }
             else {
                 id = `${Date.now().toString(36)}-${randomUUID().slice(0, 4)}`;
-                sessionName = `task-${id}`;
-                artifactDir = join(piDir, "artifacts", sessionName);
+                sessionName = taskArtifactName(id);
+                artifactDir = join(getArtifactsDir(piDir), sessionName);
                 await mkdir(artifactDir, { recursive: true });
                 resultPath = join(artifactDir, "RESULT.md");
             }
+            if (conversationId && !hasTmux()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Durable conversations require the tmux/CLI backend so Pi can save and reopen the subagent session. Install/start tmux or omit conversation_id for a one-shot SDK task.",
+                        },
+                    ],
+                    details: {
+                        phase: "failed",
+                        error: "tmux required for durable conversation",
+                        conversation_id: conversationId,
+                    },
+                    isError: true,
+                };
+            }
+            if (conversationId) {
+                await mkdir(artifactDir, { recursive: true });
+                conversationRegistry[conversationId] = taskArtifactName(id);
+                writeConversationRegistry(piDir, conversationRegistry);
+                writeConversationArtifacts({
+                    taskDir: artifactDir,
+                    taskId: id,
+                    conversationId,
+                    agentType: agent.name,
+                    sessionDir: join(artifactDir, "sessions"),
+                    sessionName,
+                    prompt: params.prompt,
+                });
+            }
             const descText = params.description || "";
             const isBackground = params.background ?? TASK_BACKGROUND_DEFAULT;
             // default true
@@ -661,6 +800,7 @@ export default function (pi) {
                     startedAt: Date.now(),
                     toolUses: 0,
                     turns: 0,
+                    conversationId,
                     recentCalls: [],
                 };
             if (foregroundTask) {
@@ -679,6 +819,7 @@ export default function (pi) {
                         startedAt: Date.now(),
                         toolUses: 0,
                         turns: 0,
+                        conversationId,
                         recentCalls: [],
                     };
                     backgroundTasks.set(id, bgtask);
@@ -690,6 +831,7 @@ export default function (pi) {
                         startedAt: bgtask.startedAt,
                         piDir,
                         dir: artifactDir,
+                        conversationId,
                     };
                     const entries = readRegistry(piDir);
                     entries.push(entry);
@@ -722,6 +864,7 @@ export default function (pi) {
                             background: true,
                             backend: "sdk",
                             result_path: resultPath,
+                            conversation_id: conversationId,
                         },
                     };
                 }
@@ -736,6 +879,7 @@ export default function (pi) {
                             backend: "sdk",
                             session_path: sessionPath,
                             result_path: resultPath,
+                            conversation_id: conversationId,
                         },
                     };
                 }
@@ -834,6 +978,7 @@ export default function (pi) {
                         tool_uses: toolUses,
                         turn_count: turns,
                         background: false,
+                        conversation_id: conversationId,
                     },
                 };
             }
@@ -848,6 +993,7 @@ export default function (pi) {
                 startedAt: Date.now(),
                 toolUses: 0,
                 turns: 0,
+                conversationId,
                 recentCalls: [],
             };
             backgroundTasks.set(id, bgtask);
@@ -861,6 +1007,7 @@ export default function (pi) {
                 paneId,
                 piDir,
                 dir: artifactDir,
+                conversationId,
             };
             // Write to JSON registry for on-load restore
             const entries = readRegistry(piDir);
@@ -974,4 +1121,12 @@ export default function (pi) {
             return new Text(line, 0, 0);
         },
     });
+    pi.registerCommand("task-sessions", {
+        description: "List durable pi-task conversations",
+        handler: async (_args, ctx) => {
+            const cwd = ctx.sessionManager?.getCwd?.() ?? process.cwd();
+            const { piDir } = discoverAgents(cwd);
+            ctx.ui.notify(renderConversationSessions(piDir), "info");
+        },
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyhuynhgiabuu/pi-task",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Delegating task/subagent extension for Pi: foreground/background subagents, widgets, tmux observability, SDK fallback.",
   "type": "module",
   "main": "./dist/index.js",