pi-long-task 0.3.9 → 0.3.11

package/src/goal_state.ts

@@ -0,0 +1,228 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  GOAL_LOOP_STATE_SCHEMA_VERSION,
+  type GoalIterationState,
+  type GoalLoopState,
+  type GoalLoopTraceEvent,
+  validateGoalLoopState,
+} from "./goal_loop.ts";
+import { type GoalSpecification, validateGoalSpecification } from "./goal_spec.ts";
+
+export const GOAL_STATE_FILE = "GOAL_STATE.json";
+export const GOAL_TRACE_FILE = "GOAL_TRACE.jsonl";
+export const GOAL_RESULT_FILE = "GOAL_RESULT.md";
+export const GOAL_SPEC_FILE = "GOAL_SPEC.json";
+
+export interface GoalStateStoreOptions {
+  cwd?: string;
+  goalRunId: string;
+  goalRunDir?: string;
+}
+
+export interface GoalStateStorePaths {
+  goalRunId: string;
+  goalRunDir: string;
+  statePath: string;
+  tracePath: string;
+  resultPath: string;
+  goalSpecPath: string;
+  iterationsDir: string;
+}
+
+export class GoalStateStore {
+  readonly paths: GoalStateStorePaths;
+
+  constructor(options: GoalStateStoreOptions) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const goalRunDir = options.goalRunDir ?? path.join(cwd, "tmp", "pi-goal-task", options.goalRunId);
+    this.paths = {
+      goalRunId: options.goalRunId,
+      goalRunDir,
+      statePath: path.join(goalRunDir, GOAL_STATE_FILE),
+      tracePath: path.join(goalRunDir, GOAL_TRACE_FILE),
+      resultPath: path.join(goalRunDir, GOAL_RESULT_FILE),
+      goalSpecPath: path.join(goalRunDir, GOAL_SPEC_FILE),
+      iterationsDir: path.join(goalRunDir, "iterations"),
+    };
+  }
+
+  async ensureRunDir(): Promise<void> {
+    await mkdir(this.paths.iterationsDir, { recursive: true });
+  }
+
+  async saveState(state: GoalLoopState): Promise<void> {
+    validateGoalLoopState(state);
+    await this.ensureRunDir();
+    await atomicWriteFile(this.paths.statePath, `${JSON.stringify(state, null, 2)}\n`);
+  }
+
+  async loadState(): Promise<GoalLoopState> {
+    const text = await readFile(this.paths.statePath, "utf8");
+    return validateGoalLoopState(JSON.parse(text));
+  }
+
+  async saveGoalSpecification(spec: GoalSpecification): Promise<void> {
+    validateGoalSpecification(spec);
+    await this.ensureRunDir();
+    await atomicWriteFile(this.paths.goalSpecPath, `${JSON.stringify(spec, null, 2)}\n`);
+  }
+
+  async loadGoalSpecification(): Promise<GoalSpecification> {
+    const text = await readFile(this.paths.goalSpecPath, "utf8");
+    return validateGoalSpecification(JSON.parse(text));
+  }
+
+  async tryLoadGoalSpecification(): Promise<GoalSpecification | undefined> {
+    try {
+      return await this.loadGoalSpecification();
+    } catch (error) {
+      if (isNodeErrnoException(error) && error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  }
+
+  async appendTrace(event: GoalLoopTraceEvent): Promise<void> {
+    await this.ensureRunDir();
+    await appendFile(this.paths.tracePath, `${JSON.stringify(event)}\n`, "utf8");
+  }
+
+  async appendNewTraceEvents(previousTraceLength: number, state: GoalLoopState): Promise<void> {
+    const events = state.trace.slice(Math.max(0, previousTraceLength));
+    for (const event of events) {
+      await this.appendTrace(event);
+    }
+  }
+
+  async initializeResult(state: GoalLoopState): Promise<void> {
+    validateGoalLoopState(state);
+    await this.ensureRunDir();
+    const lines = [
+      "# Pi Goal Task Result",
+      "",
+      `Run: ${state.goalRunId}`,
+      `Goal: ${state.goal}`,
+      `Started: ${state.startedAt}`,
+      `State: ${this.paths.statePath}`,
+      `Trace: ${this.paths.tracePath}`,
+      `Goal specification: ${this.paths.goalSpecPath}`,
+      "",
+      "## Safety limits",
+      "",
+      `- Minimum iterations before completion: ${state.limits.minIterations}`,
+      `- Max iterations: ${state.limits.maxIterations}`,
+      `- Run timeout: ${state.limits.timeoutMs}ms`,
+      `- Iteration timeout: ${state.limits.iterationTimeoutMs}ms`,
+      `- Reviewer timeout: ${state.limits.reviewerTimeoutMs}ms`,
+      "",
+    ];
+    await writeFile(this.paths.resultPath, `${lines.join("\n")}\n`, "utf8");
+  }
+
+  async appendIterationResult(iteration: GoalIterationState): Promise<void> {
+    await this.ensureRunDir();
+    const lines = [
+      "",
+      `## Iteration ${iteration.iteration}`,
+      "",
+      `Status: ${iteration.status}`,
+      `Started: ${iteration.startedAt}`,
+      `Updated: ${iteration.updatedAt}`,
+    ];
+    if (iteration.deadlineAt) {
+      lines.push(`Deadline: ${iteration.deadlineAt}`);
+    }
+    if (iteration.generatedTodo) {
+      lines.push("", "### Generated TODO", "", `Path: ${iteration.generatedTodo.todoPath}`);
+      if (iteration.generatedTodo.summary) {
+        lines.push(`Summary: ${iteration.generatedTodo.summary}`);
+      }
+    }
+    if (iteration.workerResult) {
+      lines.push(
+        "",
+        "### Worker result",
+        "",
+        `Status: ${iteration.workerResult.status}`,
+        `Summary: ${iteration.workerResult.summary}`,
+      );
+      if (iteration.workerResult.resultPath) {
+        lines.push(`Result path: ${iteration.workerResult.resultPath}`);
+      }
+      if (iteration.workerResult.todoPath) {
+        lines.push(`TODO path: ${iteration.workerResult.todoPath}`);
+      }
+      if (iteration.workerResult.taskResultPath) {
+        lines.push(`Task result path: ${iteration.workerResult.taskResultPath}`);
+      }
+      if (iteration.workerResult.workerProgressPath) {
+        lines.push(`Worker progress log: ${iteration.workerResult.workerProgressPath}`);
+      }
+      if (iteration.workerResult.error) {
+        lines.push(`Error: ${iteration.workerResult.error}`);
+      }
+    }
+    if (iteration.reviewerResult) {
+      lines.push(
+        "",
+        "### Reviewer result",
+        "",
+        `Decision: ${iteration.reviewerResult.decision}`,
+        `Complete: ${iteration.reviewerResult.complete ? "yes" : "no"}`,
+        `Summary: ${iteration.reviewerResult.summary}`,
+        `Rationale: ${iteration.reviewerResult.rationale}`,
+      );
+      if (iteration.reviewerResult.remainingWork.length > 0) {
+        lines.push("", "Remaining work:", ...iteration.reviewerResult.remainingWork.map((item) => `- ${item}`));
+      }
+    }
+    if (iteration.completion) {
+      lines.push(
+        "",
+        "### Completion",
+        "",
+        `Status: ${iteration.completion.status}`,
+        `Reason: ${iteration.completion.reason}`,
+      );
+    }
+    await appendFile(this.paths.resultPath, `${lines.join("\n")}\n`, "utf8");
+  }
+
+  async writeIterationSnapshot(iteration: GoalIterationState): Promise<string> {
+    const iterationDir = this.iterationDir(iteration.iteration);
+    await mkdir(iterationDir, { recursive: true });
+    const snapshotPath = path.join(iterationDir, "ITERATION_STATE.json");
+    await atomicWriteFile(snapshotPath, `${JSON.stringify(iteration, null, 2)}\n`);
+    return snapshotPath;
+  }
+
+  iterationDir(iteration: number): string {
+    return path.join(this.paths.iterationsDir, String(iteration).padStart(2, "0"));
+  }
+}
+
+export function goalStatePaths(options: GoalStateStoreOptions): GoalStateStorePaths {
+  return new GoalStateStore(options).paths;
+}
+
+async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  await writeFile(tmpPath, content, "utf8");
+  await rename(tmpPath, filePath);
+}
+
+export function isGoalLoopState(value: unknown): value is GoalLoopState {
+  try {
+    return validateGoalLoopState(value).schemaVersion === GOAL_LOOP_STATE_SCHEMA_VERSION;
+  } catch {
+    return false;
+  }
+}
+
+function isNodeErrnoException(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}

package/src/goal_todo_execution.ts

@@ -0,0 +1,309 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  runCoordinator,
+  type CoordinatorProgressUpdate,
+  type CoordinatorResult,
+  type RunCoordinatorOptions,
+} from "./coordinator.ts";
+import {
+  cancelGoalLoop,
+  type GoalIterationState,
+  type GoalLoopState,
+  type GoalWorkerResultState,
+  recordWorkerResult,
+} from "./goal_loop.ts";
+import { GoalStateStore } from "./goal_state.ts";
+import { validateTodoMarkdown } from "./todo_generator.ts";
+
+export const GOAL_TODO_EXECUTION_PROGRESS_FILE = "WORKER_PROGRESS.jsonl";
+
+export type GoalTodoExecutionLongTaskRunner = (options: RunCoordinatorOptions) => Promise<CoordinatorResult>;
+
+export interface GoalTodoExecutionOptions {
+  state: GoalLoopState;
+  cwd?: string;
+  store?: GoalStateStore;
+  longTaskRunner?: GoalTodoExecutionLongTaskRunner;
+  abortSignal?: AbortSignal;
+  model?: unknown;
+  modelName?: string;
+  thinkingLevel?: string;
+  maxBashTimeoutMs?: number;
+  maxAttemptsPerTask?: number;
+  commit?: boolean;
+  now?: () => Date;
+  onProgress?: (update: CoordinatorProgressUpdate) => void;
+}
+
+export interface GoalTodoExecutionResult {
+  state: GoalLoopState;
+  iteration: GoalIterationState;
+  todoMarkdown: string;
+  todoPath: string;
+  progressLogPath: string;
+  childResult: CoordinatorResult;
+}
+
+export class GoalTodoExecutionError extends Error {
+  readonly state: GoalLoopState | undefined;
+  readonly workerResult: GoalWorkerResultState | undefined;
+
+  constructor(
+    message: string,
+    options: { cause?: unknown; state?: GoalLoopState; workerResult?: GoalWorkerResultState } = {},
+  ) {
+    super(message, { cause: options.cause });
+    this.name = "GoalTodoExecutionError";
+    this.state = options.state;
+    this.workerResult = options.workerResult;
+  }
+}
+
+export async function runGoalTodoExecutionLongTask(
+  options: GoalTodoExecutionOptions,
+): Promise<GoalTodoExecutionResult> {
+  const now = options.now ?? (() => new Date());
+  let state = options.state;
+  let previousTraceLength = state.trace.length;
+  const store =
+    options.store ?? new GoalStateStore({ cwd: options.cwd, goalRunId: state.goalRunId, goalRunDir: state.goalRunDir });
+
+  const iteration = currentGeneratedIteration(state);
+  const iterationDir = store.iterationDir(iteration.iteration);
+  await mkdir(iterationDir, { recursive: true });
+  const progressLogPath = path.join(iterationDir, GOAL_TODO_EXECUTION_PROGRESS_FILE);
+
+  if (options.abortSignal?.aborted) {
+    state = cancelGoalLoop(state, "TODO execution was aborted before starting.", { now: now() });
+    await persistStateChange(store, previousTraceLength, state);
+    await store.writeIterationSnapshot(currentIteration(state, iteration.iteration));
+    throw new GoalTodoExecutionError("TODO execution was aborted before starting.", { state });
+  }
+
+  const todoPath = iteration.generatedTodo?.todoPath;
+  if (!todoPath) {
+    throw new GoalTodoExecutionError(`Goal iteration ${iteration.iteration} does not have a generated TODO path.`, {
+      state,
+    });
+  }
+
+  const todoMarkdown = await readExecutionTodoOrRecordFailure({
+    state,
+    iteration,
+    todoPath,
+    store,
+    previousTraceLength,
+    now,
+  });
+  state = todoMarkdown.state;
+  previousTraceLength = todoMarkdown.previousTraceLength;
+  try {
+    validateTodoMarkdown(todoMarkdown.content);
+  } catch (error) {
+    const failure = await recordExecutionFailure({
+      state,
+      iteration,
+      store,
+      previousTraceLength,
+      message: `Generated TODO ${todoPath} is not valid Pi Long Task markdown: ${errorMessage(error)}`,
+      error,
+      now,
+    });
+    throw new GoalTodoExecutionError(failure.workerResult.summary, {
+      cause: error,
+      state: failure.state,
+      workerResult: failure.workerResult,
+    });
+  }
+
+  const progressEvents: CoordinatorProgressUpdate[] = [];
+  const workerStartedAt = now();
+  let childResult: CoordinatorResult;
+  try {
+    childResult = await (options.longTaskRunner ?? runCoordinator)({
+      inputText: todoMarkdown.content,
+      commit: options.commit ?? true,
+      goal: state.goal,
+      cwd: options.cwd,
+      runId: `${state.goalRunId}-todo-worker-${String(iteration.iteration).padStart(2, "0")}`,
+      abortSignal: options.abortSignal,
+      workerModel: options.model,
+      workerModelName: options.modelName,
+      taskThinking: options.thinkingLevel,
+      taskTimeoutMs: timeoutForIteration(iteration, state, now()),
+      maxBashTimeoutMs: options.maxBashTimeoutMs,
+      maxAttemptsPerTask: options.maxAttemptsPerTask,
+      onProgress: (update) => {
+        progressEvents.push(update);
+        options.onProgress?.(update);
+      },
+    });
+  } catch (error) {
+    await writeProgressLog(progressLogPath, progressEvents);
+    const failure = await recordExecutionFailure({
+      state,
+      iteration,
+      store,
+      previousTraceLength,
+      progressLogPath,
+      message: `TODO execution long task failed: ${errorMessage(error)}`,
+      error,
+      now,
+    });
+    throw new GoalTodoExecutionError(failure.workerResult.summary, {
+      cause: error,
+      state: failure.state,
+      workerResult: failure.workerResult,
+    });
+  }
+
+  await writeProgressLog(progressLogPath, progressEvents);
+
+  const workerResult = workerResultFromCoordinatorResult(childResult, progressLogPath, workerStartedAt, now());
+  state = recordWorkerResult(state, iteration.iteration, workerResult, { now: now() });
+  await persistStateChange(store, previousTraceLength, state);
+  const updatedIteration = currentIteration(state, iteration.iteration);
+  await store.writeIterationSnapshot(updatedIteration);
+  await store.appendIterationResult(updatedIteration);
+
+  return {
+    state,
+    iteration: updatedIteration,
+    todoMarkdown: todoMarkdown.content,
+    todoPath,
+    progressLogPath,
+    childResult,
+  };
+}
+
+function currentGeneratedIteration(state: GoalLoopState): GoalIterationState {
+  const iteration = currentIteration(state, state.currentIteration);
+  if (iteration.status !== "todo_generated") {
+    throw new GoalTodoExecutionError(
+      `Goal iteration ${iteration.iteration} is ${iteration.status}; expected generated TODO execution.`,
+      { state },
+    );
+  }
+  return iteration;
+}
+
+function currentIteration(state: GoalLoopState, iterationNumber: number): GoalIterationState {
+  const iteration = state.iterations.find((item) => item.iteration === iterationNumber);
+  if (!iteration) {
+    throw new GoalTodoExecutionError(`Goal iteration ${iterationNumber || "<none>"} does not exist.`, { state });
+  }
+  return iteration;
+}
+
+async function readExecutionTodoOrRecordFailure(options: {
+  state: GoalLoopState;
+  iteration: GoalIterationState;
+  todoPath: string;
+  store: GoalStateStore;
+  previousTraceLength: number;
+  now: () => Date;
+}): Promise<{ state: GoalLoopState; previousTraceLength: number; content: string }> {
+  try {
+    const content = await readFile(options.todoPath, "utf8");
+    return { state: options.state, previousTraceLength: options.previousTraceLength, content };
+  } catch (error) {
+    const failure = await recordExecutionFailure({
+      state: options.state,
+      iteration: options.iteration,
+      store: options.store,
+      previousTraceLength: options.previousTraceLength,
+      message: `Could not read generated TODO ${options.todoPath}: ${errorMessage(error)}`,
+      error,
+      now: options.now,
+    });
+    throw new GoalTodoExecutionError(failure.workerResult.summary, {
+      cause: error,
+      state: failure.state,
+      workerResult: failure.workerResult,
+    });
+  }
+}
+
+async function recordExecutionFailure(options: {
+  state: GoalLoopState;
+  iteration: GoalIterationState;
+  store: GoalStateStore;
+  previousTraceLength: number;
+  message: string;
+  error: unknown;
+  now: () => Date;
+  progressLogPath?: string;
+}): Promise<{ state: GoalLoopState; workerResult: GoalWorkerResultState }> {
+  const timestamp = options.now().toISOString();
+  const workerResult: GoalWorkerResultState = {
+    status: "failed",
+    summary: options.message,
+    todoPath: options.iteration.generatedTodo?.todoPath,
+    workerProgressPath: options.progressLogPath,
+    error: errorMessage(options.error),
+    endedAt: timestamp,
+  };
+  const state = recordWorkerResult(options.state, options.iteration.iteration, workerResult, { now: options.now() });
+  await persistStateChange(options.store, options.previousTraceLength, state);
+  const updatedIteration = currentIteration(state, options.iteration.iteration);
+  await options.store.writeIterationSnapshot(updatedIteration);
+  await options.store.appendIterationResult(updatedIteration);
+  return { state, workerResult };
+}
+
+function workerResultFromCoordinatorResult(
+  childResult: CoordinatorResult,
+  progressLogPath: string,
+  startedAt: Date,
+  endedAt: Date,
+): GoalWorkerResultState {
+  return {
+    status: childResult.status,
+    summary: childResult.summary,
+    runId: childResult.runId,
+    runDir: childResult.runDir,
+    todoPath: childResult.todoPath,
+    resultPath: childResult.resultPath,
+    taskResultPath: childResult.taskResultPath,
+    totalTasks: childResult.totalTasks,
+    completedTasks: childResult.completedTasks,
+    failedTasks: childResult.failedTasks,
+    blockedTasks: childResult.blockedTasks,
+    workerCostTotal: childResult.workerCostTotal,
+    error: childResult.error,
+    workerProgressPath: progressLogPath,
+    startedAt: startedAt.toISOString(),
+    endedAt: endedAt.toISOString(),
+  };
+}
+
+async function persistStateChange(
+  store: GoalStateStore,
+  previousTraceLength: number,
+  state: GoalLoopState,
+): Promise<void> {
+  await store.saveState(state);
+  await store.appendNewTraceEvents(previousTraceLength, state);
+}
+
+async function writeProgressLog(progressLogPath: string, events: CoordinatorProgressUpdate[]): Promise<void> {
+  const content = events.map((event) => JSON.stringify(event)).join("\n");
+  await writeFile(progressLogPath, content ? `${content}\n` : "", "utf8");
+}
+
+function timeoutForIteration(iteration: GoalIterationState, state: GoalLoopState, now: Date): number {
+  if (!iteration.deadlineAt) {
+    return state.limits.iterationTimeoutMs;
+  }
+  const remaining = Date.parse(iteration.deadlineAt) - now.getTime();
+  if (!Number.isFinite(remaining) || remaining <= 0) {
+    return 1_000;
+  }
+  return Math.min(state.limits.iterationTimeoutMs, Math.max(1_000, Math.floor(remaining)));
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}