pi-long-task 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dejan Jacimovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# Pi Long Task
+
+Pi Long Task is a Pi extension that turns a larger coding request into a clear TODO plan, works through the tasks one by one, and reports the result.
+
+It is useful when you want Pi to handle a multi-step change without losing track of what has been done, what is still left, and whether changes should be committed.
+
+## What you get
+
+When you ask Pi to use `pi_long_task`, it will:
+
+1. Create or clean up a TODO plan from your request.
+2. Work through each unfinished TODO task in order.
+3. Record progress and final results under `tmp/pi-long-task/<run-id>/`.
+4. Return a summary with completed, failed, blocked, and remaining task counts.
+5. Optionally commit completed work after each task.
+
+A finished run gives you:
+
+- a concise status summary in Pi
+- a generated `TODO.md`
+- a generated `TASK_RESULT.md`
+- commit hashes when commits were enabled and created
+- any remaining or blocked tasks clearly listed
+
+## Install
+
+After this package is published to npm, install it with:
+
+```bash
+pi install npm:pi-long-task
+```
+
+For local development, load this checkout for one Pi session:
+
+```bash
+pi -e /path/to/pi-long-task
+```
+
+Or install the local checkout so Pi can load it normally:
+
+```bash
+pi install /path/to/pi-long-task
+```
+
+After installing, start `pi` in your target project and ask it to use the `pi_long_task` tool.
+
+## Usage
+
+Run without commits:
+
+```text
+Use pi_long_task with inputText "add tests for the parser and fix any failures" and commit false.
+```
+
+Run and allow commits:
+
+```text
+Use pi_long_task with inputText "implement the TODOs in @TODO.md" and commit true.
+```
+
+Use a pasted TODO plan:
+
+```text
+Use pi_long_task with inputText "<paste TODO markdown here>" and commit false.
+```
+
+## Options
+
+The tool has two inputs:
+
+```ts
+{
+  inputText: string;
+  commit: boolean;
+}
+```
+
+- `inputText` is the request or TODO markdown to work on.
+- `commit` controls whether Pi Long Task may create git commits.
+
+No other public options are required.
+
+## Commits and files
+
+When `commit` is `false`, Pi Long Task never creates commits.
+
+When `commit` is `true`, it may commit eligible task changes after a task reports useful progress. It avoids committing:
+
+- generated run files under `tmp/pi-long-task/`
+- generated `TASK_RESULT.md` files
+- files that were already dirty before the task started
+
+This lets you keep existing local work separate from Pi Long Task changes.
+
+## Validate the install
+
+Run the local checks:
+
+```bash
+cd /path/to/pi-long-task
+npm run check
+```
+
+Check that Pi can load the extension:
+
+```bash
+PI_OFFLINE=1 pi --mode json --no-extensions -e /path/to/pi-long-task --no-session
+```
+
+Run the full native smoke test if Pi has usable model credentials:
+
+```bash
+npm run smoke:native
+```
+
+That smoke test creates disposable git repos and verifies both `commit: false` and `commit: true` runs.
+
+## Notes
+
+- Tasks run one at a time.
+- Real runs require a working Pi model/login or API key.
+- Run artifacts are written under `tmp/pi-long-task/<run-id>/`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-long-task",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension for breaking down and running long coding tasks safely.",
+  "keywords": [
+    "pi-package",
+    "long-task",
+    "task-runner",
+    "coding-agent",
+    "pi-extension"
+  ],
+  "files": [
+    "LICENSE",
+    "README.md",
+    "scripts",
+    "src"
+  ],
+  "scripts": {
+    "test": "node --experimental-strip-types --test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "smoke:native": "node scripts/native_smoke.mjs"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.74.2",
+    "@earendil-works/pi-coding-agent": "^0.74.2",
+    "@earendil-works/pi-tui": "^0.74.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.3",
+    "eslint": "^10.5.0",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.4",
+    "typebox": "^1.2.13",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.1"
+  },
+  "license": "MIT",
+  "author": "Dejan Jacimovic <dejan@stuntcoders.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thestuntcoder/pi-long-task.git"
+  },
+  "bugs": {
+    "url": "https://github.com/thestuntcoder/pi-long-task/issues"
+  },
+  "homepage": "https://github.com/thestuntcoder/pi-long-task#readme"
+}

package/scripts/native_smoke.mjs

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtemp, rm, mkdir } from "node:fs/promises";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..");
+
+const PI_BINARY = process.env.PI_BINARY || "pi";
+const EXTENSION_PATH = path.resolve(process.env.PI_COORDINATOR_EXTENSION || repoRoot);
+const MODEL = process.env.PI_SMOKE_MODEL || "openai-codex/gpt-5.5:minimal";
+const TIMEOUT_MS = positiveInteger(process.env.PI_SMOKE_TIMEOUT_MS, 20 * 60 * 1000);
+const KEEP = truthy(process.env.PI_SMOKE_KEEP);
+
+const cases = [
+  {
+    name: "commit-false",
+    commit: false,
+    markerFile: "SMOKE_FALSE.txt",
+    markerText: "commit false smoke ok",
+    title: "Create non-commit smoke marker",
+    goal: "Verify Pi Long Task can modify the disposable repo while commits are disabled.",
+  },
+  {
+    name: "commit-true",
+    commit: true,
+    markerFile: "SMOKE_TRUE.txt",
+    markerText: "commit true smoke ok",
+    title: "Create commit smoke marker",
+    goal: "Verify Pi Long Task can modify the disposable repo and commit eligible changes.",
+  },
+];
+
+const smokeRoot = await mkdtemp(path.join(os.tmpdir(), "pi-long-task-native-smoke-"));
+let success = false;
+
+try {
+  console.log(`Native Pi Long Task smoke root: ${smokeRoot}`);
+  console.log(`Extension: ${EXTENSION_PATH}`);
+  console.log(`Outer model: ${MODEL}`);
+
+  const summaries = [];
+  for (const testCase of cases) {
+    summaries.push(await runSmokeCase(testCase));
+  }
+
+  success = true;
+  console.log("\nNative Pi Long Task smoke passed:");
+  for (const summary of summaries) {
+    const commitText = summary.commitHash ? `, Pi Long Task commit ${summary.commitHash}` : "";
+    console.log(`- ${summary.name}: ${summary.status}, marker verified${commitText}`);
+  }
+} finally {
+  if (success && !KEEP) {
+    await rm(smokeRoot, { recursive: true, force: true });
+  } else {
+    console.log(`Smoke artifacts kept at: ${smokeRoot}`);
+  }
+}
+
+async function runSmokeCase(testCase) {
+  const caseDir = path.join(smokeRoot, testCase.name);
+  const repoDir = path.join(caseDir, "repo");
+  await mkdir(repoDir, { recursive: true });
+  initializeGitRepo(repoDir, testCase.name);
+
+  const prompt = buildPrompt(testCase);
+  const stdoutPath = path.join(caseDir, "pi.stdout.jsonl");
+  const stderrPath = path.join(caseDir, "pi.stderr.log");
+  const args = [
+    "-p",
+    "--mode",
+    "json",
+    "--no-session",
+    "--no-extensions",
+    "-e",
+    EXTENSION_PATH,
+    "--no-context-files",
+    "--no-skills",
+    "--no-prompt-templates",
+    "--tools",
+    "pi_long_task",
+    "--model",
+    MODEL,
+    prompt,
+  ];
+
+  console.log(`\n[${testCase.name}] running Pi in ${repoDir}`);
+  const result = await runProcess(PI_BINARY, args, {
+    cwd: repoDir,
+    env: {
+      ...process.env,
+      PI_SKIP_VERSION_CHECK: process.env.PI_SKIP_VERSION_CHECK || "1",
+    },
+    timeoutMs: TIMEOUT_MS,
+    stdoutPath,
+    stderrPath,
+  });
+
+  if (result.code !== 0) {
+    throw new Error(`[${testCase.name}] pi exited with ${result.code}. stdout: ${stdoutPath}; stderr: ${stderrPath}`);
+  }
+
+  const events = parseJsonEvents(result.stdout);
+  const longTaskEnd = events.find((event) => event.type === "tool_execution_end" && event.toolName === "pi_long_task");
+  if (!longTaskEnd) {
+    throw new Error(`[${testCase.name}] did not observe pi_long_task tool_execution_end in ${stdoutPath}`);
+  }
+  if (longTaskEnd.isError) {
+    throw new Error(`[${testCase.name}] pi_long_task ended with isError=true. See ${stdoutPath}`);
+  }
+
+  const details = longTaskEnd.result?.details;
+  assertLongTaskDetails(testCase, details, stdoutPath);
+  assertMarker(repoDir, testCase.markerFile, testCase.markerText);
+  assertGitState(repoDir, testCase, details);
+
+  const summary = {
+    name: testCase.name,
+    status: details.status,
+    commitHash: details.commits?.[0]?.hash,
+  };
+  console.log(`[${testCase.name}] ok; stdout: ${stdoutPath}`);
+  return summary;
+}
+
+function initializeGitRepo(repoDir, caseName) {
+  runGit(["init", "-q"], repoDir);
+  runGit(["config", "user.email", "smoke@example.invalid"], repoDir);
+  runGit(["config", "user.name", "Pi Long Task Smoke"], repoDir);
+  writeFileSync(path.join(repoDir, "README.md"), `# ${caseName}\n`, "utf8");
+  runGit(["add", "README.md"], repoDir);
+  runGit(["commit", "-q", "-m", "init"], repoDir);
+}
+
+function buildPrompt(testCase) {
+  return `Call the \`pi_long_task\` tool exactly once. Do not use any other tool and do not answer from your own knowledge.
+Use these exact parameters:
+- commit: ${String(testCase.commit)}
+- inputText:
+\`\`\`markdown
+# TODO
+
+## TODO 1 — ${testCase.title}
+
+**Goal:** ${testCase.goal}
+
+**Status:**
+- [ ] Create a file named \`${testCase.markerFile}\` containing exactly \`${testCase.markerText}\` followed by a newline.
+- [ ] Verify it by running \`cat ${testCase.markerFile}\`.
+\`\`\``;
+}
+
+function assertLongTaskDetails(testCase, details, stdoutPath) {
+  if (!details || typeof details !== "object") {
+    throw new Error(`[${testCase.name}] missing Pi Long Task result details. See ${stdoutPath}`);
+  }
+  const expected = {
+    status: "done",
+    totalTasks: 1,
+    completedTasks: 1,
+    failedTasks: 0,
+    blockedTasks: 0,
+  };
+  for (const [key, value] of Object.entries(expected)) {
+    if (details[key] !== value) {
+      throw new Error(`[${testCase.name}] expected details.${key}=${value}, got ${details[key]}. See ${stdoutPath}`);
+    }
+  }
+  const commitCount = Array.isArray(details.commits) ? details.commits.length : 0;
+  if (testCase.commit && commitCount !== 1) {
+    throw new Error(`[${testCase.name}] expected one Pi Long Task commit, got ${commitCount}. See ${stdoutPath}`);
+  }
+  if (!testCase.commit && commitCount !== 0) {
+    throw new Error(`[${testCase.name}] expected zero Pi Long Task commits, got ${commitCount}. See ${stdoutPath}`);
+  }
+}
+
+function assertMarker(repoDir, markerFile, markerText) {
+  const markerPath = path.join(repoDir, markerFile);
+  if (!existsSync(markerPath)) {
+    throw new Error(`missing smoke marker ${markerPath}`);
+  }
+  const actual = readFileSync(markerPath, "utf8");
+  const expected = `${markerText}\n`;
+  if (actual !== expected) {
+    throw new Error(`unexpected marker contents in ${markerPath}: ${JSON.stringify(actual)}`);
+  }
+}
+
+function assertGitState(repoDir, testCase, details) {
+  const commitCount = Number(runGit(["rev-list", "--count", "HEAD"], repoDir).trim());
+  const status = runGit(["status", "--short", "--untracked-files=all"], repoDir);
+
+  if (testCase.commit) {
+    if (commitCount !== 2) {
+      throw new Error(`[${testCase.name}] expected exactly 2 commits after commit=true run, got ${commitCount}`);
+    }
+    const changedInHead = runGit(["diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD"], repoDir)
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .sort();
+    if (JSON.stringify(changedInHead) !== JSON.stringify([testCase.markerFile])) {
+      throw new Error(
+        `[${testCase.name}] expected HEAD to contain only ${testCase.markerFile}, got ${changedInHead.join(", ")}`,
+      );
+    }
+    if (!details.commits?.[0]?.hash) {
+      throw new Error(`[${testCase.name}] missing commit hash in Pi Long Task details`);
+    }
+    if (status.includes(testCase.markerFile)) {
+      throw new Error(`[${testCase.name}] committed marker still appears dirty in git status:\n${status}`);
+    }
+  } else {
+    if (commitCount !== 1) {
+      throw new Error(`[${testCase.name}] expected no new commits after commit=false run, got ${commitCount}`);
+    }
+    if (!status.includes(`?? ${testCase.markerFile}`)) {
+      throw new Error(`[${testCase.name}] expected uncommitted marker in git status, got:\n${status}`);
+    }
+  }
+
+  const trackedArtifacts = runGit(["ls-files", "tmp/pi-long-task"], repoDir).trim();
+  if (trackedArtifacts) {
+    throw new Error(`[${testCase.name}] Pi Long Task artifacts were tracked unexpectedly:\n${trackedArtifacts}`);
+  }
+}
+
+function runGit(args, cwd) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(`git ${args.join(" ")} failed in ${cwd}: ${result.stderr || result.stdout}`);
+  }
+  return result.stdout;
+}
+
+function runProcess(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 5_000).unref();
+      reject(new Error(`${command} timed out after ${options.timeoutMs}ms`));
+    }, options.timeoutMs);
+
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+      appendFileSync(options.stdoutPath, chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+      appendFileSync(options.stderrPath, chunk);
+    });
+    child.on("error", (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    });
+    child.on("close", (code, signal) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      resolve({ code, signal, stdout, stderr });
+    });
+  });
+}
+
+function appendFileSync(filePath, chunk) {
+  writeFileSync(filePath, chunk, { encoding: "utf8", flag: "a" });
+}
+
+function parseJsonEvents(stdout) {
+  const events = [];
+  for (const rawLine of stdout.split(/\n/)) {
+    const jsonStart = rawLine.indexOf("{");
+    if (jsonStart === -1) {
+      continue;
+    }
+    const line = rawLine.slice(jsonStart).trim();
+    if (!line) {
+      continue;
+    }
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Pi may emit terminal control sequences next to JSON in some terminals.
+      // Keep parsing best-effort; missing required events are asserted later.
+    }
+  }
+  return events;
+}
+
+function truthy(value) {
+  return ["1", "true", "yes", "on"].includes(String(value || "").toLowerCase());
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}