pi-long-task 0.3.8 → 0.3.10

package/src/session_guard.ts

@@ -0,0 +1,287 @@
+import {
+  assistantTextFromEvent,
+  lastAssistantTextFromEvents,
+  lastAssistantTextFromMessages,
+  type WorkerSessionLike,
+} from "./worker_session.ts";
+
+export interface GuardedSessionPromptOptions {
+  session: WorkerSessionLike;
+  prompt: string;
+  promptOptions?: Record<string, unknown>;
+  abortSignal?: AbortSignal;
+  timeoutMs?: number;
+  gracefulShutdownMs?: number;
+  gracefulShutdownPrompt?: string;
+  diagnostics?: string[];
+  onEvent?: (event: unknown) => void;
+  dispose?: boolean;
+}
+
+export interface GuardedSessionPromptResult {
+  assistantText: string;
+  timedOut: boolean;
+  aborted: boolean;
+  error?: string;
+  diagnostics: string[];
+  events: unknown[];
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export async function runGuardedSessionPrompt(
+  options: GuardedSessionPromptOptions,
+): Promise<GuardedSessionPromptResult> {
+  const session = options.session;
+  const diagnostics = [...(options.diagnostics ?? [])];
+  const events: unknown[] = [];
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  let assistantText = "";
+  let timedOut = false;
+  let aborted = false;
+  let error: string | undefined;
+  let promptSettled = false;
+  let finished = false;
+  let unsubscribe: (() => void) | undefined;
+  let complete: (() => void) | undefined;
+
+  const completed = new Promise<void>((resolve) => {
+    complete = resolve;
+  });
+
+  const resolveCompleted = () => {
+    complete?.();
+    complete = undefined;
+  };
+
+  const clearTimers = () => {
+    for (const timer of timers) {
+      clearTimeout(timer);
+    }
+    timers.clear();
+  };
+
+  const schedule = (fn: () => void, ms: number) => {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      fn();
+    }, ms);
+    timers.add(timer);
+  };
+
+  const abortSession = (reason: string) => {
+    if (finished || aborted) {
+      return;
+    }
+    aborted = true;
+    error = error ?? reason;
+    try {
+      const abortResult = session.abort?.();
+      if (isPromiseLike(abortResult)) {
+        void abortResult.catch((exc: unknown) => {
+          diagnostics.push(`session abort failed: ${errorMessage(exc)}`);
+        });
+      }
+    } catch (exc) {
+      diagnostics.push(`session abort failed: ${errorMessage(exc)}`);
+    }
+  };
+
+  const requestGracefulShutdown = () => {
+    const message = options.gracefulShutdownPrompt?.trim();
+    if (!message || finished || promptSettled || aborted) {
+      return;
+    }
+
+    try {
+      if (session.isBashRunning && session.abortBash) {
+        session.abortBash();
+        diagnostics.push("aborted running bash before graceful shutdown request");
+      }
+
+      let request: Promise<unknown> | undefined;
+      if ((session.isStreaming || session.isBashRunning) && session.steer) {
+        request = session.steer(message);
+      } else if (session.followUp) {
+        request = session.followUp(message);
+      } else if (session.steer) {
+        request = session.steer(message);
+      }
+
+      if (!request) {
+        diagnostics.push("graceful shutdown request skipped: session does not support steer/followUp");
+        return;
+      }
+
+      void request.catch((exc: unknown) => {
+        diagnostics.push(`graceful shutdown request failed: ${errorMessage(exc)}`);
+      });
+    } catch (exc) {
+      diagnostics.push(`graceful shutdown request failed: ${errorMessage(exc)}`);
+    }
+  };
+
+  const triggerTimeout = () => {
+    if (finished || promptSettled || timedOut) {
+      return;
+    }
+    timedOut = true;
+    diagnostics.push(`session prompt timed out after ${formatMilliseconds(timeoutMs(options.timeoutMs))}`);
+    requestGracefulShutdown();
+
+    const graceMs = nonNegativeMilliseconds(options.gracefulShutdownMs);
+    const hardAbort = () => {
+      if (finished || promptSettled) {
+        return;
+      }
+      abortSession(`session prompt exceeded ${formatMilliseconds(timeoutMs(options.timeoutMs))} timeout`);
+      resolveCompleted();
+    };
+
+    if (graceMs > 0) {
+      schedule(hardAbort, graceMs);
+    } else {
+      hardAbort();
+    }
+  };
+
+  const abortListener = () => {
+    if (finished || promptSettled) {
+      return;
+    }
+    abortSession(abortReason(options.abortSignal, "session prompt aborted by outer signal"));
+    resolveCompleted();
+  };
+
+  try {
+    if (options.abortSignal?.aborted) {
+      aborted = true;
+      error = abortReason(options.abortSignal, "session prompt aborted before start");
+    } else {
+      unsubscribe = session.subscribe((event: unknown) => {
+        events.push(event);
+        const text = assistantTextFromEvent(event);
+        if (text) {
+          assistantText = text;
+        }
+        try {
+          options.onEvent?.(event);
+        } catch (exc) {
+          diagnostics.push(`event listener failed: ${errorMessage(exc)}`);
+        }
+      });
+
+      options.abortSignal?.addEventListener("abort", abortListener, { once: true });
+
+      const promptPromise = session.prompt(options.prompt, options.promptOptions).then(
+        () => {
+          promptSettled = true;
+          resolveCompleted();
+        },
+        (exc: unknown) => {
+          promptSettled = true;
+          error = error ?? errorMessage(exc);
+          resolveCompleted();
+        },
+      );
+      void promptPromise;
+
+      const limitMs = timeoutMs(options.timeoutMs);
+      if (limitMs > 0) {
+        schedule(triggerTimeout, limitMs);
+      }
+
+      await completed;
+    }
+  } catch (exc) {
+    error = error ?? errorMessage(exc);
+  } finally {
+    finished = true;
+    clearTimers();
+    options.abortSignal?.removeEventListener("abort", abortListener);
+    unsubscribe?.();
+    assistantText = latestAssistantText(session, events, assistantText);
+    if (options.dispose !== false) {
+      try {
+        const disposeResult = (session.dispose as (() => unknown) | undefined)?.();
+        if (isPromiseLike(disposeResult)) {
+          await disposeResult;
+        }
+      } catch (exc) {
+        const message = `session dispose failed: ${errorMessage(exc)}`;
+        diagnostics.push(message);
+        error = error ?? message;
+      }
+    }
+  }
+
+  return buildResult(session, events, assistantText, timedOut, aborted, error, diagnostics);
+}
+
+function buildResult(
+  session: WorkerSessionLike,
+  events: unknown[],
+  assistantText: string,
+  timedOut: boolean,
+  aborted: boolean,
+  error: string | undefined,
+  diagnostics: string[],
+): GuardedSessionPromptResult {
+  return {
+    assistantText: latestAssistantText(session, events, assistantText),
+    timedOut,
+    aborted,
+    error,
+    diagnostics: [...diagnostics],
+    events: [...events],
+    sessionFile: session.sessionFile,
+    sessionId: session.sessionId,
+  };
+}
+
+function latestAssistantText(session: WorkerSessionLike, events: unknown[], fallback: string): string {
+  const direct = session.getLastAssistantText?.();
+  if (direct) {
+    return direct;
+  }
+  const fromMessages = lastAssistantTextFromMessages(session.messages);
+  if (fromMessages) {
+    return fromMessages;
+  }
+  const fromEvents = lastAssistantTextFromEvents(events);
+  return fromEvents || fallback;
+}
+
+function timeoutMs(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+
+function nonNegativeMilliseconds(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return 0;
+  }
+  return Math.max(0, value);
+}
+
+function formatMilliseconds(ms: number): string {
+  return `${(ms / 1000).toFixed(3)}s`;
+}
+
+function abortReason(signal: AbortSignal | undefined, fallback: string): string {
+  const reason = signal?.reason;
+  if (reason === undefined) {
+    return fallback;
+  }
+  return errorMessage(reason);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}

package/src/todo_generator.ts

@@ -1,3 +1,9 @@
+import {
+  coverageGoalAction,
+  coverageGoalVerification,
+  coverageGoalVerifyBullet,
+  parseCoverageGoal,
+} from "./coverage_goal.ts";
 import { parseTasks, TodoParseError } from "./todo_parser.ts";
 
 const TODO_HEADING_RE = /^##\s+TODO\s+(\d+)\s+[—-]\s+(.+?)\s*$/gm;
@@ -20,21 +26,21 @@ interface ExistingTask {
   body: string;
 }
 
-export function todoMarkdownFromString(rawInput: string): string | undefined {
+export function todoMarkdownFromString(rawInput: string, goal?: string): string | undefined {
   const input = rawInput.trim();
   if (!input) {
     return undefined;
   }
 
   if (hasTodoHeadings(input)) {
-    const markdown = normalizeExistingTodoMarkdown(input);
+    const markdown = applyGoalInstructionsToTodoMarkdown(normalizeExistingTodoMarkdown(input), goal);
     validateTodoMarkdown(markdown);
     return markdown;
   }
 
   const listItems = simpleListItems(input);
   if (listItems.length >= 2) {
-    const markdown = generatedTodoMarkdown(listItems);
+    const markdown = applyGoalInstructionsToTodoMarkdown(generatedTodoMarkdown(listItems), goal);
     validateTodoMarkdown(markdown);
     return markdown;
   }
@@ -116,8 +122,140 @@ export function validateTodoMarkdown(markdown: string): void {
   });
 }
 
-export function buildTodoCreationPrompt(rawInput: string): string {
-  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.\n\nRequirements:\n- Output only markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n\nRaw input:\n\n${rawInput.trim()}\n`;
+export function applyGoalInstructionsToTodoMarkdown(markdown: string, goal?: string): string {
+  const trimmedGoal = oneLine(goal ?? "");
+  if (!trimmedGoal) {
+    return markdown;
+  }
+
+  let next = insertGlobalGoalInstructions(markdown, trimmedGoal);
+  const coverageGoal = parseCoverageGoal(trimmedGoal);
+  if (coverageGoal) {
+    next = appendCoverageVerificationToTasks(next, coverageGoalVerifyBullet(coverageGoal));
+  }
+  validateTodoMarkdown(next);
+  return next;
+}
+
+function insertGlobalGoalInstructions(markdown: string, goal: string): string {
+  const coverageGoal = parseCoverageGoal(goal);
+  const additions = [`- Long task goal: ${goal}`];
+  if (coverageGoal) {
+    additions.push(`- Coverage goal: ${coverageGoalAction(coverageGoal)}`);
+    additions.push(`- Coverage verification: ${coverageGoalVerification(coverageGoal)}`);
+  }
+
+  const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+  const progressIndex = lines.findIndex((line) => /^##\s+Progress\s*$/i.test(line.trim()));
+  if (progressIndex < 0) {
+    return markdown;
+  }
+
+  const existingGlobalText = lines.slice(0, progressIndex).join("\n");
+  const missing = additions.filter((line) => !existingGlobalText.includes(line));
+  if (missing.length === 0) {
+    return markdown;
+  }
+
+  const before = trimTrailingBlankLines(lines.slice(0, progressIndex));
+  const after = trimLeadingBlankLines(lines.slice(progressIndex));
+  const hasGlobalHeading = /^Global instructions:\s*$/im.test(existingGlobalText);
+  const block = hasGlobalHeading ? missing : ["Global instructions:", ...missing];
+  return ensureTrailingNewline([...before, "", ...block, "", ...after].join("\n"));
+}
+
+function appendCoverageVerificationToTasks(markdown: string, verificationBullet: string): string {
+  const tasks = parseTasks(markdown);
+  const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+  for (const task of [...tasks].reverse()) {
+    if (task.section.includes(verificationBullet)) {
+      continue;
+    }
+
+    const startIndex = task.startLine - 1;
+    const endIndex = task.endLine;
+    const verifyIndex = findVerifyLineIndex(lines, startIndex, endIndex);
+    if (verifyIndex >= 0) {
+      lines.splice(verifyIndex + 1, 0, verificationBullet);
+      continue;
+    }
+
+    const doneIndex = findDoneWhenLineIndex(lines, startIndex, endIndex);
+    const insertIndex = doneIndex >= 0 ? doneIndex : endIndex;
+    lines.splice(insertIndex, 0, "**Verify:**", verificationBullet, "");
+  }
+
+  return ensureTrailingNewline(lines.join("\n"));
+}
+
+function findVerifyLineIndex(lines: readonly string[], startIndex: number, endIndex: number): number {
+  for (let idx = startIndex; idx < endIndex; idx += 1) {
+    if (/^\*\*Verify:\*\*/i.test(lines[idx].trim())) {
+      return idx;
+    }
+  }
+  return -1;
+}
+
+function findDoneWhenLineIndex(lines: readonly string[], startIndex: number, endIndex: number): number {
+  for (let idx = startIndex; idx < endIndex; idx += 1) {
+    if (/^\*\*Done when:\*\*/i.test(lines[idx].trim())) {
+      return idx;
+    }
+  }
+  return -1;
+}
+
+function trimTrailingBlankLines(lines: string[]): string[] {
+  while (lines.at(-1)?.trim() === "") {
+    lines.pop();
+  }
+  return lines;
+}
+
+function trimLeadingBlankLines(lines: string[]): string[] {
+  while (lines[0]?.trim() === "") {
+    lines.shift();
+  }
+  return lines;
+}
+
+function oneLine(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function buildTodoCreationPrompt(rawInput: string, goal?: string): string {
+  const goalBlock = todoGoalPromptBlock(goal);
+  return `Convert the following raw project request into Pi Long Task-compatible TODO markdown.\n\nRequirements:\n- Output only markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n${goalBlock}\nRaw input:\n\n${rawInput.trim()}\n`;
+}
+
+export function buildTodoRepairPrompt(
+  rawInput: string,
+  invalidOutput: string,
+  validationError: string,
+  goal?: string,
+): string {
+  const goalBlock = todoGoalPromptBlock(goal);
+  return `Your previous response was not valid Pi Long Task TODO markdown. Correct it now.\n\nValidation/extraction error:\n${validationError.trim() || "Unknown validation error."}\n\nRequirements:\n- Output only corrected markdown, with no commentary and no code fence.\n- Start with exactly: # Pi Long Task TODO\n- Include a ## Progress section with one unchecked line per task: - [ ] TODO N — Title\n- Include a --- separator before task sections.\n- Create sequential sections named ## TODO N — Title.\n- Each task section must include **Goal:**, **Status:** with unchecked checkbox items, **Verify:** with concrete verification guidance, and **Done when:**.\n- Preserve any global instructions or constraints that apply to all tasks above ## Progress.\n- Keep tasks focused and independently assignable to worker sessions.\n${goalBlock}\nOriginal raw input:\n\n${rawInput.trim()}\n\nPrevious invalid output:\n\n${invalidOutput.trim()}\n`;
+}
+
+function todoGoalPromptBlock(goal: string | undefined): string {
+  const trimmed = goal?.trim();
+  if (!trimmed) {
+    return "";
+  }
+
+  const coverageGoal = parseCoverageGoal(trimmed);
+  const coverageBlock = coverageGoal
+    ? `\nCoverage goal requirements:\n- Include global instructions that tell workers to ${coverageGoalAction(coverageGoal)}\n- Include verification guidance that tells workers to ${coverageGoalVerification(coverageGoal)}\n- Do not hardcode a fixed coverage threshold; use the requested threshold (${coverageGoal.thresholdText}%).\n`
+    : "";
+  return `\nOverall goal:\n\n${trimmed}\n${coverageBlock}`;
+}
+
+export function extractAndValidateTodoMarkdown(assistantText: string): string {
+  const markdown = extractTodoMarkdown(assistantText);
+  validateTodoMarkdown(markdown);
+  return markdown;
 }
 
 export function extractTodoMarkdown(assistantText: string): string {

package/src/types.ts

@@ -6,18 +6,80 @@ import type { SessionOutcome } from "./worker_session.ts";
 
 export const PiLongTaskParams = Type.Object(
   {
-    inputText: Type.String({
-      description: "TODO file content or the user's long-task instructions to process.",
-    }),
+    inputText: Type.Optional(
+      Type.String({
+        description:
+          "Optional TODO file content or the user's long-task instructions to process. Natural-language routing parses commit and goal separately.",
+      }),
+    ),
     commit: Type.Boolean({
       description:
         "Whether Pi Long Task may commit completed worker changes. Use true when the user asks for commits or committing as work progresses; otherwise use false.",
     }),
+    goal: Type.Optional(
+      Type.String({
+        description: "Optional high-level goal or desired outcome for the long-task run.",
+      }),
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export const PiGoalTaskParams = Type.Object(
+  {
+    goal: Type.String({
+      description:
+        "High-level goal to achieve through repeated TODO generation, long-task execution, and reviewer iterations until complete or stopped by limits.",
+    }),
+    commit: Type.Optional(
+      Type.Boolean({
+        description:
+          "Whether worker long tasks may commit completed TODO work during the goal loop. Defaults to true for goal loops.",
+      }),
+    ),
+    maxIterations: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Maximum number of generate → execute → review iterations before stopping. Defaults to 50.",
+      }),
+    ),
+    timeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Overall goal-loop timeout in milliseconds. Defaults to 172800000 (48 hours).",
+      }),
+    ),
+    iterationTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description:
+          "Timeout budget in milliseconds for each generated TODO worker iteration. Defaults to 10800000 (3 hours).",
+      }),
+    ),
+    reviewerTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Timeout budget in milliseconds for each reviewer session. Defaults to 1800000 (30 minutes).",
+      }),
+    ),
+    maxAttemptsPerTask: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Maximum attempts for each TODO inside worker long-task runs.",
+      }),
+    ),
+    maxBashTimeoutMs: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        description: "Maximum bash command timeout in milliseconds allowed in worker sessions.",
+      }),
+    ),
   },
   { additionalProperties: false },
 );
 
 export type PiLongTaskInput = Static<typeof PiLongTaskParams>;
+export type PiGoalTaskInput = Static<typeof PiGoalTaskParams>;
 
 export type CoordinatorStatus = "done" | "partial" | "blocked" | "failed";
 
@@ -64,5 +126,6 @@ export interface PiLongTaskResult {
   taskProgress: TaskProgressModel;
   workerCostTotal: number;
   commit: boolean;
+  goal?: string;
   error?: string;
 }

package/src/worker_session.ts

@@ -1,3 +1,4 @@
+import { coverageGoalAction, coverageGoalVerification, parseCoverageGoal } from "./coverage_goal.ts";
 import { hasTaskResult, hasTaskResultStatus, isDoneStatus, parseReportedStatus } from "./result_writer.ts";
 import type { Task } from "./todo_parser.ts";
 
@@ -8,6 +9,7 @@ export interface WorkerTaskPromptOptions {
   commitRequested: boolean;
   previousAttempts?: string;
   globalInstructions?: string;
+  goal?: string;
   maxBashTimeoutSeconds: number;
 }
 
@@ -22,7 +24,7 @@ export function taskLabel(task: Pick<Task, "taskId" | "title">): string {
 
 export function buildTaskPrompt(options: WorkerTaskPromptOptions): string {
   const commitText = options.commitRequested
-    ? "Pi Long Task will commit after your session if needed. Do not run git commit."
+    ? "Commit mode is enabled: complete your assigned work and report status accurately; Pi Long Task will commit eligible completed work after your session if needed. Do not run git commit."
     : "Do not run git commit. Pi Long Task was started with commits disabled.";
 
   const previousAttempts = (options.previousAttempts || "").trim();
@@ -47,11 +49,30 @@ ${globalInstructions}
 `
     : "";
 
+  const goal = (options.goal || "").trim();
+  const coverageGoal = parseCoverageGoal(goal);
+  const coverageGoalText = coverageGoal
+    ? `
+
+Coverage goal guidance:
+- ${coverageGoalAction(coverageGoal)}
+- ${coverageGoalVerification(coverageGoal)} Prefer the project-specific coverage script when available (for example, \`npm run test:coverage\`, \`npm run coverage\`, or \`npm test -- --coverage\`).`
+    : "";
+  const goalText = goal
+    ? `
+
+Long task goal:
+
+\`\`\`text
+${goal}
+\`\`\`${coverageGoalText}`
+    : "";
+
   return `You are one Pi SDK worker session assigned to exactly one TODO task.
 
 Assigned TODO file path: \`${options.todoPath}\`
 Assigned task: \`${taskLabel(options.task)}\`
-Attempt: ${options.attempt}
+Attempt: ${options.attempt}${goalText}
 
 Rules:
 - Work only on the assigned task below. Do not start or fix other TODO tasks.