@kky42/pi-goal 1.0.0

package/src/goal-runtime-turn-handlers.ts

@@ -0,0 +1,66 @@
+import type {
+  ExtensionHandler,
+  TurnEndEvent,
+  TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import { assistantTurnTokens, isAbortedAssistantMessage, isToolUseAssistantMessage } from "./goal-accounting.js";
+import { isAssistantContextOverflow, isErrorAssistantMessage } from "./recovery.js";
+import { getContextWindow, runStaleQueuedWorkPlan } from "./goal-runtime-event-utils.js";
+import type {
+  GoalRuntimeTurnHandlerContext,
+  ToolExecutionEndEvent,
+} from "./goal-runtime-event-handler-types.js";
+
+export function createTurnEventHandlers(deps: GoalRuntimeTurnHandlerContext) {
+  const { runtimeState, stateController, continuation, goalAccounting, recoveryRuntime, status } = deps;
+
+  return {
+    onTurnStart: (async (event, ctx) => {
+      runtimeState.currentTurnIndex = event.turnIndex;
+      continuation.bindPassthroughContinuationInputToTurn(event.turnIndex);
+      runStaleQueuedWorkPlan(runtimeState.staleQueuedWorkGuard.planTurnStart(), ctx, deps);
+      goalAccounting.beginAccounting();
+      status.refreshUi(ctx);
+    }) satisfies ExtensionHandler<TurnStartEvent>,
+
+    onToolExecutionEnd: (async (_event, ctx) => {
+      if (runStaleQueuedWorkPlan(runtimeState.staleQueuedWorkGuard.planToolExecutionEnd(), ctx, deps)) {
+        return;
+      }
+
+      goalAccounting.accountProgress(ctx, true, 0, true);
+      stateController.maybeFlushRuntimePersistence("runtime");
+    }) satisfies ExtensionHandler<ToolExecutionEndEvent>,
+
+    onTurnEnd: (async (event, ctx) => {
+      if (
+        runStaleQueuedWorkPlan(
+          runtimeState.staleQueuedWorkGuard.planTurnEnd(event.turnIndex),
+          ctx,
+          deps,
+        )
+      ) {
+        return;
+      }
+
+      const completedTurnTokens = assistantTurnTokens(event.message);
+      goalAccounting.accountProgress(ctx, true, completedTurnTokens);
+      stateController.flushGoalPersistence("runtime");
+      if (isAbortedAssistantMessage(event.message)) {
+        stateController.pauseForAbort(ctx);
+        return;
+      }
+      if (isErrorAssistantMessage(event.message)) {
+        return;
+      }
+      if (isAssistantContextOverflow(event.message, getContextWindow(ctx))) {
+        stateController.beginOverflowRecovery(ctx);
+        return;
+      }
+      recoveryRuntime.finishSuccessfulAssistantTurn(event.message, ctx, {
+        continueGoal: !isToolUseAssistantMessage(event.message),
+      });
+    }) satisfies ExtensionHandler<TurnEndEvent>,
+  };
+}

package/src/goal-state-controller.ts

@@ -0,0 +1,210 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { GoalPersistence } from "./goal-persistence.js";
+import type { StatusContext } from "./goal-runtime-status.js";
+import {
+  applyGoalTransitionEffects,
+  planGoalTransition,
+  type GoalTransitionEffect,
+  type GoalTransitionEffectHandlers,
+  type GoalTransitionRequest,
+} from "./goal-transition.js";
+import {
+  applyHostOverflowUserResetPersistence,
+  beginHostOverflowRecovery,
+  requireHostOverflowUserReset,
+  syncHostOverflowUserResetFromSession,
+  type GoalRecoveryMachineState,
+} from "./recovery-machine.js";
+import {
+  goalsEquivalent,
+  hostOverflowCapResetEntry,
+  reconstructGoal,
+  reconstructHostOverflowCapNeedsUserReset,
+  updateGoalStatus,
+} from "./state.js";
+import { CUSTOM_ENTRY_TYPE, type GoalEntrySource, type GoalResult, type ThreadGoal } from "./types.js";
+
+interface GoalStateControllerDeps {
+  pi: Pick<ExtensionAPI, "appendEntry">;
+  persistence: GoalPersistence;
+  getRecoveryState: () => GoalRecoveryMachineState;
+  transitionEffectHandlers: GoalTransitionEffectHandlers;
+  refreshUi: (ctx: StatusContext) => void;
+}
+
+function reloadRuntimeEffects(
+  previousGoalId: string | null,
+  reconstructed: ThreadGoal | null,
+): GoalTransitionEffect[] {
+  const effects: GoalTransitionEffect[] = [{ type: "clearContinuation" }];
+  if (reconstructed?.status !== "active") {
+    effects.push({ type: "clearActiveAccounting" });
+  }
+  if ((reconstructed?.goalId ?? null) !== previousGoalId) {
+    effects.push({ type: "resetRecovery" });
+  }
+  return effects;
+}
+
+export interface GoalStateController {
+  applyGoalTransition: (
+    request: GoalTransitionRequest,
+    ctx: StatusContext | null,
+  ) => boolean;
+  beginOverflowRecovery: (ctx: StatusContext) => void;
+  updateGoal: (status: "complete" | "blocked", source: GoalEntrySource, ctx: ExtensionContext) => GoalResult;
+  flushGoalPersistence: GoalPersistence["flushGoalPersistence"];
+  getGoal: () => ThreadGoal | null;
+  isCurrentActiveGoalId: (goalId: string) => boolean;
+  maybeFlushRuntimePersistence: GoalPersistence["maybeFlushRuntimePersistence"];
+  pauseForAbort: (ctx: ExtensionContext) => void;
+  persistHostOverflowUserReset: (needsReset: boolean) => void;
+  reloadFromSession: (ctx: ExtensionContext) => void;
+  resumePausedGoal: (ctx: ExtensionContext) => void;
+}
+
+export function createGoalStateController(deps: GoalStateControllerDeps) {
+  const getGoal = (): ThreadGoal | null => deps.persistence.getGoal();
+
+  const isCurrentActiveGoalId = (goalId: string): boolean =>
+    getGoal()?.goalId === goalId && getGoal()?.status === "active";
+
+  const applyGoalTransition = (
+    request: GoalTransitionRequest,
+    ctx: StatusContext | null,
+  ): boolean => {
+    const plan = planGoalTransition(getGoal(), request);
+
+    applyGoalTransitionEffects(plan.beforePersist, deps.transitionEffectHandlers);
+
+    if (plan.persist === "clear") {
+      const clearedGoalId = getGoal()?.goalId ?? null;
+      deps.persistence.appendClearEntry(clearedGoalId, plan.source);
+      applyGoalTransitionEffects(plan.afterPersist, deps.transitionEffectHandlers);
+      if (ctx) {
+        deps.refreshUi(ctx);
+      }
+      return true;
+    }
+
+    if (plan.persist === "skip") {
+      applyGoalTransitionEffects(plan.afterPersist, deps.transitionEffectHandlers);
+      if (ctx) {
+        deps.refreshUi(ctx);
+      }
+      return false;
+    }
+
+    if (plan.persist === "defer") {
+      deps.persistence.setGoalSnapshot(plan.nextGoal);
+      if (ctx) {
+        deps.refreshUi(ctx);
+      }
+      return false;
+    }
+
+    deps.persistence.setGoalSnapshot(plan.nextGoal);
+    const persisted = deps.persistence.flushGoalPersistence(plan.source);
+    applyGoalTransitionEffects(plan.afterPersist, deps.transitionEffectHandlers);
+    if (ctx) {
+      deps.refreshUi(ctx);
+    }
+
+    return persisted;
+  };
+
+  const persistHostOverflowUserReset = (needsReset: boolean): void => {
+    if (!applyHostOverflowUserResetPersistence(deps.getRecoveryState(), needsReset)) {
+      return;
+    }
+    deps.pi.appendEntry(CUSTOM_ENTRY_TYPE, hostOverflowCapResetEntry(needsReset));
+  };
+
+  const beginOverflowRecovery = (ctx: StatusContext): void => {
+    const goal = getGoal();
+    const hasActiveGoal = Boolean(goal && goal.status === "active");
+    let shouldPersist: boolean;
+
+    if (hasActiveGoal) {
+      applyGoalTransitionEffects([{ type: "clearContinuation" }], deps.transitionEffectHandlers);
+      const { persistHostOverflowCapReset } = beginHostOverflowRecovery(deps.getRecoveryState());
+      shouldPersist = persistHostOverflowCapReset;
+      deps.refreshUi(ctx);
+    } else {
+      shouldPersist = requireHostOverflowUserReset(deps.getRecoveryState());
+    }
+
+    if (shouldPersist) {
+      deps.pi.appendEntry(CUSTOM_ENTRY_TYPE, hostOverflowCapResetEntry(true));
+    }
+  };
+
+  const reloadFromSession = (ctx: ExtensionContext): void => {
+    const previousGoalId = getGoal()?.goalId ?? null;
+    const branch = ctx.sessionManager.getBranch();
+    const reconstructed = reconstructGoal(branch).goal;
+    deps.persistence.setGoalSnapshot(reconstructed);
+    deps.persistence.syncPersistedSnapshot(reconstructed);
+    syncHostOverflowUserResetFromSession(
+      deps.getRecoveryState(),
+      reconstructHostOverflowCapNeedsUserReset(branch),
+    );
+    applyGoalTransitionEffects(
+      reloadRuntimeEffects(previousGoalId, reconstructed),
+      deps.transitionEffectHandlers,
+    );
+    deps.refreshUi(ctx);
+  };
+
+  const pauseForAbort = (ctx: ExtensionContext): void => {
+    const goal = getGoal();
+    if (!goal || goal.status !== "active") {
+      return;
+    }
+
+    applyGoalTransition({ kind: "abort_pause" }, ctx);
+  };
+
+  const resumePausedGoal = (ctx: ExtensionContext): void => {
+    const goal = getGoal();
+    if (!goal || (goal.status !== "paused" && goal.status !== "blocked")) {
+      return;
+    }
+
+    applyGoalTransition({ kind: "resume_active" }, ctx);
+  };
+
+  const updateGoal = (
+    status: "complete" | "blocked",
+    source: GoalEntrySource,
+    ctx: ExtensionContext,
+  ): GoalResult => {
+    const goal = getGoal();
+    const result = updateGoalStatus(goal, status);
+    if (!result.ok || !result.goal) {
+      return result;
+    }
+    if (goal && goalsEquivalent(goal, result.goal)) {
+      return result;
+    }
+    applyGoalTransition({ kind: "set", nextGoal: result.goal, source }, ctx);
+    return result;
+  };
+
+  const controller: GoalStateController = {
+    applyGoalTransition,
+    beginOverflowRecovery,
+    updateGoal,
+    flushGoalPersistence: deps.persistence.flushGoalPersistence,
+    getGoal,
+    isCurrentActiveGoalId,
+    maybeFlushRuntimePersistence: deps.persistence.maybeFlushRuntimePersistence,
+    pauseForAbort,
+    persistHostOverflowUserReset,
+    reloadFromSession,
+    resumePausedGoal,
+  };
+
+  return controller;
+}

package/src/goal-transition-effects.ts

@@ -0,0 +1,91 @@
+export type GoalTransitionEffect =
+  | { type: "clearContinuation" }
+  | { type: "clearActiveAccounting" }
+  | { type: "resetRecovery" }
+  | { type: "clearBudgetWarning" }
+  | { type: "clearHostOverflowRecovery" }
+  | { type: "setRecoveryPausedAttention"; reason: string }
+  | { type: "markContinuationQueued"; goalId: string }
+  | { type: "stopStatusRefresh" };
+
+export interface GoalTransitionEffectHandlers {
+  clearContinuation: () => void;
+  clearActiveAccounting: () => void;
+  resetRecovery: () => void;
+  clearBudgetWarning: () => void;
+  clearHostOverflowRecovery: () => void;
+  setRecoveryPausedAttention: (reason: string) => void;
+  markContinuationQueued: (goalId: string) => void;
+  stopStatusRefresh: () => void;
+}
+
+function goalTransitionEffectKey(effect: GoalTransitionEffect): string {
+  switch (effect.type) {
+    case "setRecoveryPausedAttention":
+      return `${effect.type}:${effect.reason}`;
+    case "markContinuationQueued":
+      return `${effect.type}:${effect.goalId}`;
+    default:
+      return effect.type;
+  }
+}
+
+export function appendGoalTransitionEffectOnce(
+  effects: GoalTransitionEffect[],
+  effect: GoalTransitionEffect,
+): void {
+  const key = goalTransitionEffectKey(effect);
+  if (!effects.some((existing) => goalTransitionEffectKey(existing) === key)) {
+    effects.push(effect);
+  }
+}
+
+export function mergeGoalTransitionEffects(
+  ...groups: readonly GoalTransitionEffect[][]
+): GoalTransitionEffect[] {
+  const result: GoalTransitionEffect[] = [];
+  for (const group of groups) {
+    for (const effect of group) {
+      appendGoalTransitionEffectOnce(result, effect);
+    }
+  }
+  return result;
+}
+
+export function applyGoalTransitionEffects(
+  effects: readonly GoalTransitionEffect[],
+  handlers: GoalTransitionEffectHandlers,
+): void {
+  for (const effect of effects) {
+    switch (effect.type) {
+      case "clearContinuation":
+        handlers.clearContinuation();
+        break;
+      case "clearActiveAccounting":
+        handlers.clearActiveAccounting();
+        break;
+      case "resetRecovery":
+        handlers.resetRecovery();
+        break;
+      case "clearBudgetWarning":
+        handlers.clearBudgetWarning();
+        break;
+      case "clearHostOverflowRecovery":
+        handlers.clearHostOverflowRecovery();
+        break;
+      case "setRecoveryPausedAttention":
+        handlers.setRecoveryPausedAttention(effect.reason);
+        break;
+      case "markContinuationQueued":
+        handlers.markContinuationQueued(effect.goalId);
+        break;
+      case "stopStatusRefresh":
+        handlers.stopStatusRefresh();
+        break;
+      default: {
+        const _exhaustive: never = effect;
+        throw new Error(`Unhandled goal transition effect: ${String(_exhaustive)}`);
+      }
+    }
+  }
+}