@harms-haus/pi-tasks 0.1.0

package/src/formatting.ts

@@ -0,0 +1,201 @@
+import type { TaskBoardSnapshot, TaskRecord, TaskStatus } from "./types";
+import { STATUS_ICONS } from "./types";
+import { getStatusCounts } from "./validation";
+
+// ── Plain-Text Formatting (for LLM tool output) ──
+
+/** Returns a phase label string including the title if available. */
+export function phaseLabel(board: TaskBoardSnapshot, phaseNum: number): string {
+  const rec = board.phases.find((p) => p.phase === phaseNum);
+  return rec?.title ? `Phase ${phaseNum}: ${rec.title}` : `Phase ${phaseNum}`;
+}
+
+/** Returns the plain-text icon for a task status. */
+function getStatusIcon(status: TaskStatus): string {
+  return STATUS_ICONS[status];
+}
+
+/** Format a single task as a plain-text line. */
+function formatTaskLine(task: TaskRecord): string {
+  return `${getStatusIcon(task.status)} ${task.id}: ${task.title}`;
+}
+
+/** Format the full board as a plain-text summary for LLM consumption. */
+export function formatBoardText(
+  board: TaskBoardSnapshot,
+  options?: { activePhaseOnly?: boolean; counts?: Record<TaskStatus, number> },
+): string {
+  if (board.tasks.length === 0) return "No tasks on the board.";
+
+  const lines: string[] = ["Task Board:", ""];
+
+  const activePhaseOnly = options?.activePhaseOnly === true;
+  const activePhaseRecord = board.phases.find((p) => p.status === "active");
+  const useActiveOnly = activePhaseOnly && activePhaseRecord !== undefined;
+
+  // Determine which phases to render
+  const phases = useActiveOnly
+    ? [activePhaseRecord.phase]
+    : [...new Set(board.tasks.map((t) => t.phase))].sort((a, b) => a - b);
+
+  for (const phase of phases) {
+    lines.push(`─── ${phaseLabel(board, phase)} ───`);
+    const phaseTasks = board.tasks.filter((t) => t.phase === phase);
+    for (const task of phaseTasks) {
+      let line = formatTaskLine(task);
+      if (task.dependencies.length > 0) {
+        line += ` → depends on ${task.dependencies.join(", ")}`;
+      }
+      lines.push(line);
+    }
+    lines.push("");
+  }
+
+  // Summary line (always across ALL phases)
+  const counts = options?.counts ?? getStatusCounts(board);
+  const parts: string[] = [];
+  for (const [status, count] of Object.entries(counts)) {
+    if (count > 0) parts.push(`${count} ${status}`);
+  }
+  lines.push(`Summary: ${parts.join(", ")}`);
+
+  return lines.join("\n");
+}
+
+/** Format a short summary for tool output headers. */
+export function formatSummaryLine(
+  board: TaskBoardSnapshot,
+  counts?: Record<TaskStatus, number>,
+): string {
+  const total = board.tasks.length;
+  const done = counts
+    ? counts.done + counts.abandoned
+    : board.tasks.filter((t) => t.status === "done" || t.status === "abandoned").length;
+  const activePhase = board.phases.find((p) => p.status === "active");
+  return activePhase
+    ? `${phaseLabel(board, activePhase.phase)} · ${done}/${total} done`
+    : `${done}/${total} done`;
+}
+
+/** Format claimed task details with prompt preview. */
+export function formatClaimedTaskDetails(tasks: TaskRecord[]): string {
+  return tasks
+    .map((t) => {
+      const lines = [`${getStatusIcon(t.status)} ${t.id}: ${t.title}  (${t.profile})`];
+      const promptLines = t.prompt.split("\n");
+      const shown = promptLines.slice(0, 3);
+      lines.push(...shown);
+      if (promptLines.length > 3) {
+        lines.push("  ... (truncated)");
+      }
+      return lines.join("\n");
+    })
+    .join("\n\n");
+}
+
+/** Format the hidden context message for before_agent_start injection. */
+export function formatHiddenContext(board: TaskBoardSnapshot): string {
+  const lines: string[] = ["[PHASED TASKS ACTIVE]", ""];
+
+  const activePhase = board.phases.find((p) => p.status === "active");
+  lines.push(`Active Phase: ${activePhase ? phaseLabel(board, activePhase.phase) : "none"}`);
+
+  // Counts by status
+  const counts = getStatusCounts(board);
+  lines.push(
+    `Status: ${Object.entries(counts)
+      .filter(([, c]) => c > 0)
+      .map(([s, c]) => `${c} ${s}`)
+      .join(", ")}`,
+  );
+
+  // Currently claimed tasks
+  const claimed = board.tasks.filter(
+    (t) => t.status === "implementing" || t.status === "reviewing",
+  );
+  if (claimed.length > 0) {
+    lines.push("");
+    lines.push("Currently claimed:");
+    for (const t of claimed) {
+      lines.push(`  ${getStatusIcon(t.status)} [${t.id}] ${t.title}`);
+    }
+  }
+
+  // Non-terminal tasks
+  lines.push("");
+  lines.push("Remaining tasks:");
+  const nonTerminal = board.tasks.filter((t) => t.status !== "done" && t.status !== "abandoned");
+  for (const t of nonTerminal) {
+    lines.push(`  ${formatTaskLine(t)}`);
+  }
+
+  // Recently completed (up to 10)
+  const terminal = board.tasks.filter((t) => t.status === "done" || t.status === "abandoned");
+  if (terminal.length > 0) {
+    lines.push("");
+    lines.push("Recently completed:");
+    const sorted = [...terminal].sort(
+      (a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+    );
+    const recent = sorted.slice(0, 10);
+    if (terminal.length > 10) {
+      lines.push(`  ... and ${terminal.length - 10} more terminal tasks`);
+    }
+    for (const t of recent) {
+      lines.push(`  ${formatTaskLine(t)}`);
+    }
+  }
+
+  lines.push("");
+  lines.push(
+    "Workflow: write_tasks → edit_tasks (blockers/data) → compile_tasks → get_ready_tasks → advance_tasks → done",
+  );
+
+  return lines.join("\n");
+}
+
+/** Format the auto-continue prompt. */
+export function formatContinuePrompt(board: TaskBoardSnapshot): string {
+  const ready = board.tasks.filter((t) => t.status === "ready");
+  const active = board.tasks.filter((t) => t.status === "implementing" || t.status === "reviewing");
+
+  if (ready.length > 0 || active.length > 0) {
+    const lines: string[] = ["Tasks remain. Continue working on the phased task board."];
+    if (active.length > 0) {
+      lines.push("");
+      lines.push("Currently claimed:");
+      for (const t of active) {
+        lines.push(`  [${t.id}] ${t.title} (${t.status})`);
+      }
+    }
+    if (ready.length > 0) {
+      lines.push("");
+      lines.push(`Ready to claim: ${ready.length} task(s). Call get_ready_tasks to claim them.`);
+    }
+    return lines.join("\n");
+  }
+
+  // Deadlock
+  const nonTerminal = board.tasks.filter((t) => t.status !== "done" && t.status !== "abandoned");
+  if (nonTerminal.length > 0) {
+    return [
+      "The task board is blocked — no tasks are ready, implementing, or reviewing, but tasks remain.",
+      "Inspect dependencies and phase gating. Use edit_tasks to resolve blockers, then compile_tasks.",
+      "",
+      "Blocked tasks:",
+      ...nonTerminal.map(
+        (t) => `  [${t.id}] ${t.title} (${t.status}, ${phaseLabel(board, t.phase)})`,
+      ),
+    ].join("\n");
+  }
+
+  return "";
+}
+
+/** Format the "all done" terminal message. */
+export function formatAllDoneMessage(board: TaskBoardSnapshot): string {
+  if (board.phases.length === 0) return "All tasks resolved.";
+  const lastPhaseRecord = board.phases[board.phases.length - 1];
+  if (!lastPhaseRecord) return "All tasks resolved.";
+  return `All tasks resolved. ${phaseLabel(board, lastPhaseRecord.phase)} complete.`;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerMessageRenderers } from "./renderers";
+import { registerEventHandlers } from "./events";
+import {
+  createWriteTasksTool,
+  createEditTasksTool,
+  createCompileTasksTool,
+  createClearTasksTool,
+  createGetReadyTasksTool,
+  createAdvanceTasksTool,
+} from "./tools";
+
+export default function (pi: ExtensionAPI): void {
+  registerMessageRenderers(pi);
+  registerEventHandlers(pi);
+
+  pi.registerTool(createWriteTasksTool(pi));
+  pi.registerTool(createEditTasksTool(pi));
+  pi.registerTool(createCompileTasksTool(pi));
+  pi.registerTool(createClearTasksTool(pi));
+  pi.registerTool(createGetReadyTasksTool(pi));
+  pi.registerTool(createAdvanceTasksTool(pi));
+}

package/src/renderers.ts

@@ -0,0 +1,28 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+export function registerMessageRenderers(pi: ExtensionAPI): void {
+  pi.registerMessageRenderer("phased-tasks-context", (message, _opts, theme) => {
+    return new Text(
+      theme.fg("accent", "📋 ") +
+        theme.fg(
+          "dim",
+          typeof message.content === "string" ? message.content : JSON.stringify(message.content),
+        ),
+      0,
+      0,
+    );
+  });
+
+  pi.registerMessageRenderer("phased-tasks-notice", (message, _opts, theme) => {
+    return new Text(
+      theme.fg("warning", "⚠ ") +
+        theme.fg(
+          "text",
+          typeof message.content === "string" ? message.content : JSON.stringify(message.content),
+        ),
+      0,
+      0,
+    );
+  });
+}

package/src/schemas.ts

@@ -0,0 +1,65 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+// ── Schemas ──
+
+export const WriteTasksParams = Type.Object({
+  mode: StringEnum(["replace", "append"], {
+    description: "'replace' clears the board before writing; 'append' adds to existing tasks",
+  }),
+  phases: Type.Array(
+    Type.Object({
+      title: Type.String({ description: "Short phase title" }),
+      tasks: Type.Array(
+        Type.Object({
+          title: Type.String({ description: "Short task title" }),
+          prompt: Type.String({ description: "Detailed implementation instructions" }),
+          profile: Type.String({ description: "Agent profile name for task delegation" }),
+        }),
+        { description: "Tasks in this phase (at least 1)", minItems: 1 },
+      ),
+    }),
+    { description: "Phases to write to the board", minItems: 1 },
+  ),
+});
+
+export const EditTasksParams = Type.Object({
+  tasks: Type.Array(
+    Type.Union([
+      Type.Object({
+        id: Type.String(),
+        type: StringEnum(["data"]),
+        data: Type.Object({
+          title: Type.Optional(Type.String()),
+          prompt: Type.Optional(Type.String()),
+          profile: Type.Optional(Type.String()),
+          phase: Type.Optional(Type.Integer()),
+        }),
+      }),
+      Type.Object({
+        id: Type.String(),
+        type: StringEnum(["blockers"]),
+        data: Type.Object({
+          dependencies: Type.Array(Type.String()),
+        }),
+      }),
+      Type.Object({
+        id: Type.String(),
+        type: StringEnum(["abandon"]),
+      }),
+    ]),
+    { maxItems: 50 },
+  ),
+});
+
+export const CompileTasksParams = Type.Object({});
+
+export const ClearTasksParams = Type.Object({});
+
+export const GetReadyTasksParams = Type.Object({
+  count: Type.Integer({ description: "Number of tasks to claim (>= 1)", minimum: 1 }),
+});
+
+export const AdvanceTasksParams = Type.Object({
+  ids: Type.Array(Type.String(), { description: "Task IDs to advance", maxItems: 50 }),
+});

package/src/state.ts

@@ -0,0 +1,124 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TaskBoardSnapshot } from "./types";
+import { CUSTOM_EVENT_TYPE, CUSTOM_SNAPSHOT_TYPE } from "./types";
+import { createEmptyBoard } from "./engine";
+import { isValidSnapshot, cloneBoard, getStatusCounts } from "./validation";
+import { phaseLabel } from "./formatting";
+
+// ── Mutable State ──
+
+let board: TaskBoardSnapshot = createEmptyBoard();
+let autoContinueCount = 0;
+let lastToolWasAdvance = false;
+
+// ── State Accessors ──
+
+/** Returns a deep copy of the current board. */
+export function getBoard(): TaskBoardSnapshot {
+  return cloneBoard(board);
+}
+
+/** Replaces the board state. Resets auto-continue counter. */
+export function setBoard(newBoard: TaskBoardSnapshot): void {
+  board = cloneBoard(newBoard);
+  autoContinueCount = 0;
+}
+
+/** Replaces the board state without resetting the auto-continue counter. Used internally by the auto-continue loop. */
+export function setBoardQuiet(newBoard: TaskBoardSnapshot): void {
+  board = cloneBoard(newBoard);
+}
+
+/** Returns a readonly reference to the current board (no clone — caller must not mutate). */
+export function getBoardRef(): Readonly<TaskBoardSnapshot> {
+  return board;
+}
+
+/** Increments and returns the auto-continue counter. */
+export function incrementAutoContinue(): number {
+  return ++autoContinueCount;
+}
+
+/** Returns whether the last tool result was from advance_tasks. */
+export function getLastToolWasAdvance(): boolean {
+  return lastToolWasAdvance;
+}
+
+/** Set the last-tool-was-advance flag. */
+export function setLastToolWasAdvance(value: boolean): void {
+  lastToolWasAdvance = value;
+}
+
+/** Resets all mutable state. For testing only. */
+export function resetState(): void {
+  board = createEmptyBoard();
+  autoContinueCount = 0;
+  lastToolWasAdvance = false;
+}
+
+// ── State Reconstruction ──
+
+/**
+ * Reconstructs board state from session history.
+ * Scans the branch in reverse to find the latest phased-tasks:snapshot custom entry.
+ * Falls back to empty board if no valid snapshot found.
+ */
+export function reconstructState(ctx: ExtensionContext): TaskBoardSnapshot {
+  const branch = ctx.sessionManager.getBranch();
+
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (!entry) continue;
+    if (entry.type !== "custom") continue;
+    if ((entry as { customType?: string }).customType !== CUSTOM_SNAPSHOT_TYPE) continue;
+    const data = (entry as { data?: unknown }).data;
+    if (data && isValidSnapshot(data)) {
+      return cloneBoard(data);
+    }
+  }
+
+  return createEmptyBoard();
+}
+
+// ── Persistence Helpers ──
+
+/** Append both an event and a snapshot entry. */
+export function persistEntries(
+  pi: ExtensionAPI,
+  event: unknown,
+  snapshot: TaskBoardSnapshot,
+): void {
+  pi.appendEntry(CUSTOM_EVENT_TYPE, event);
+  pi.appendEntry(CUSTOM_SNAPSHOT_TYPE, snapshot);
+}
+
+// ── UI Sync ──
+
+/** Updates the status bar to reflect current board state. */
+export function updateUI(ctx: ExtensionContext, snapshot: Readonly<TaskBoardSnapshot>): void {
+  if (!ctx.hasUI) return;
+
+  if (snapshot.tasks.length === 0) {
+    ctx.ui.setStatus("til-done", undefined);
+    ctx.ui.setStatus("til-done-active", undefined);
+    return;
+  }
+
+  const counts = getStatusCounts(snapshot);
+
+  const done = counts.done + counts.abandoned;
+  const total = snapshot.tasks.length;
+
+  const activePhase = snapshot.phases.find((p) => p.status === "active");
+  const label = activePhase ? phaseLabel(snapshot, activePhase.phase) : "No active phase";
+
+  ctx.ui.setStatus("til-done", `${done}/${total} - ${label}`);
+
+  const activeLines: string[] = [];
+  for (const t of snapshot.tasks) {
+    if (t.status === "implementing" || t.status === "reviewing") {
+      activeLines.push(`[${t.id}] ${t.title}`);
+    }
+  }
+  ctx.ui.setStatus("til-done-active", activeLines.length > 0 ? activeLines.join("\n") : undefined);
+}