@kky42/pi-goal 1.0.0

package/src/recovery-runtime.ts

@@ -0,0 +1,97 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  onRecoverySessionCompact,
+  onRecoverySuccessfulTurn,
+  onRecoveryUserInput,
+  planRecoveryForAssistantError,
+  planRecoveryForSilentContextOverflow,
+  setRecoveryPendingAttention,
+  type GoalRecoveryMachineState,
+  type RecoveryAction,
+} from "./recovery-machine.js";
+import type { AssistantErrorMessage } from "./recovery.js";
+import type { ThreadGoal } from "./types.js";
+
+interface RecoveryRuntimeDeps {
+  getGoal: () => ThreadGoal | null;
+  getRecoveryState: () => GoalRecoveryMachineState;
+  clearContinuationState: () => void;
+  pauseGoalForRecovery: (ctx: ExtensionContext, recoveryReason: string) => void;
+  refreshUi: (ctx: ExtensionContext) => void;
+  requestContinuation: (ctx: ExtensionContext) => void;
+}
+
+export function createGoalRecoveryRuntime(deps: RecoveryRuntimeDeps) {
+  const pauseForRecoveryAttention = (ctx: ExtensionContext, reason: string): void => {
+    const goal = deps.getGoal();
+    if (!goal || goal.status !== "active") {
+      return;
+    }
+
+    deps.pauseGoalForRecovery(ctx, reason);
+  };
+
+  const applyRecoveryAction = (action: RecoveryAction, ctx: ExtensionContext): void => {
+    switch (action.type) {
+      case "noop":
+        return;
+      case "pending": {
+        const goal = deps.getGoal();
+        if (!goal || goal.status !== "active") {
+          return;
+        }
+        deps.clearContinuationState();
+        setRecoveryPendingAttention(deps.getRecoveryState(), action.reason);
+        deps.refreshUi(ctx);
+        return;
+      }
+      case "pause":
+        pauseForRecoveryAttention(ctx, action.reason);
+        return;
+    }
+  };
+
+  const handlePersistentAssistantError = (message: AssistantErrorMessage, ctx: ExtensionContext): void => {
+    const goal = deps.getGoal();
+    if (!goal || goal.status !== "active") {
+      return;
+    }
+
+    applyRecoveryAction(planRecoveryForAssistantError(deps.getRecoveryState(), message), ctx);
+  };
+
+  const handleSilentContextOverflow = (ctx: ExtensionContext): void => {
+    const goal = deps.getGoal();
+    if (!goal || goal.status !== "active") {
+      return;
+    }
+
+    applyRecoveryAction(planRecoveryForSilentContextOverflow(deps.getRecoveryState()), ctx);
+  };
+
+  const finishSuccessfulAssistantTurn = (
+    message: AssistantErrorMessage,
+    ctx: ExtensionContext,
+    options?: { continueGoal?: boolean },
+  ): void => {
+    if (onRecoverySuccessfulTurn(deps.getRecoveryState(), message)) {
+      deps.refreshUi(ctx);
+      if (options?.continueGoal !== false) {
+        deps.requestContinuation(ctx);
+      }
+    }
+  };
+
+  return {
+    onUserInput: () => {
+      onRecoveryUserInput(deps.getRecoveryState());
+    },
+    onSessionCompact: () => {
+      onRecoverySessionCompact(deps.getRecoveryState());
+    },
+    handlePersistentAssistantError,
+    handleSilentContextOverflow,
+    finishSuccessfulAssistantTurn,
+  };
+}

package/src/recovery.ts

@@ -0,0 +1,151 @@
+import { isContextOverflow } from "@earendil-works/pi-ai";
+
+import { assistantMessageForOverflowCheck } from "./recovery-adapters.js";
+
+export const CONTEXT_OVERFLOW_SIGNATURE = "context_overflow";
+
+/** Host AgentSession performs one overflow compact-and-retry before giving up. */
+export const MAX_CONTEXT_COMPACTION_RETRIES = 1;
+export const HOST_OVERFLOW_RECOVERY_REASON = "recovering from context overflow";
+
+const RECOVERY_PENDING_ATTENTION_SUFFIX =
+  "wait for host retry/compaction or send a new user message if it does not recover.";
+
+export interface AssistantErrorMessage {
+  role: string;
+  stopReason?: string;
+  errorMessage?: string;
+  usage?: {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+}
+
+export interface ErrorRecoveryCounters {
+  signature: string | null;
+  transientAttempts: number;
+  compactionAttempts: number;
+}
+
+export function createErrorRecoveryCounters(): ErrorRecoveryCounters {
+  return {
+    signature: null,
+    transientAttempts: 0,
+    compactionAttempts: 0,
+  };
+}
+
+export function isErrorAssistantMessage(message: AssistantErrorMessage): boolean {
+  return message.role === "assistant" && message.stopReason === "error";
+}
+
+export function isSuccessfulAssistantTurn(message: AssistantErrorMessage): boolean {
+  if (message.role !== "assistant") {
+    return false;
+  }
+  return message.stopReason !== "error" && message.stopReason !== "aborted";
+}
+
+export function isAssistantContextOverflow(
+  message: AssistantErrorMessage,
+  contextWindow: number,
+): boolean {
+  if (message.role !== "assistant") {
+    return false;
+  }
+  if (contextWindow <= 0) {
+    return isContextOverflowError(message.errorMessage);
+  }
+  return isContextOverflow(assistantMessageForOverflowCheck(message), contextWindow);
+}
+
+export function isContextOverflowError(errorMessage: string | undefined): boolean {
+  return isContextOverflow(
+    assistantMessageForOverflowCheck({
+      stopReason: "error",
+      errorMessage: errorMessage ?? "",
+    }),
+  );
+}
+
+function isNonRetryableProviderLimitError(errorMessage: string): boolean {
+  return /GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|available balance|insufficient_quota|out of budget|quota exceeded|billing/i.test(
+    errorMessage,
+  );
+}
+
+/**
+ * Mirrors Pi 0.76.0 host AgentSession._isRetryableError() classification for transient provider failures.
+ * Context overflow is not transient retryable because host compaction handles that path.
+ * Terminal quota, billing, and provider-limit errors are not retryable even when they contain 429 or rate-limit wording.
+ */
+export function isRetryableTransientError(errorMessage: string | undefined): boolean {
+  if (!errorMessage) {
+    return false;
+  }
+  if (isContextOverflowError(errorMessage)) {
+    return false;
+  }
+  if (isNonRetryableProviderLimitError(errorMessage)) {
+    return false;
+  }
+  return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|connection.?lost|websocket.?closed|websocket.?error|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|ended without|stream ended before message_stop|http2 request did not get a response|timed? out|timeout|terminated|retry delay/i.test(
+    errorMessage,
+  );
+}
+
+function normalizeTransientSignature(line: string): string {
+  return line
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, "<id>")
+    .replace(/\breq[_-]?[a-z0-9-]+\b/gi, "req_<id>")
+    .replace(/\b\d{4,}\b/g, "<n>")
+    .slice(0, 200);
+}
+
+export function failureSignature(errorMessage: string | undefined): string {
+  if (isContextOverflowError(errorMessage)) {
+    return CONTEXT_OVERFLOW_SIGNATURE;
+  }
+  const message = (errorMessage ?? "unknown_error").trim();
+  const firstLine = message.split("\n")[0] ?? message;
+  return normalizeTransientSignature(firstLine);
+}
+
+/** Resets transient retry counters when the failure signature changes; overflow compaction attempts are independent. */
+export function countersForFailureSignature(
+  counters: ErrorRecoveryCounters,
+  signature: string,
+): ErrorRecoveryCounters {
+  if (counters.signature === signature) {
+    return counters;
+  }
+  return {
+    signature,
+    transientAttempts: 0,
+    compactionAttempts: counters.compactionAttempts,
+  };
+}
+
+export function recoveryPendingAttentionMessage(reason: string): string {
+  return `Goal recovery pending (${reason}); ${RECOVERY_PENDING_ATTENTION_SUFFIX}`;
+}
+
+export function isRecoveryPendingAttention(attention: string | null): boolean {
+  return attention?.startsWith("Goal recovery pending (") ?? false;
+}
+
+export function reasonFromRecoveryPendingAttention(attention: string): string | null {
+  const match = /^Goal recovery pending \((.+)\); /.exec(attention);
+  return match?.[1] ?? null;
+}
+
+export function recoveryPausedAttentionMessage(reason: string): string {
+  return `Goal needs attention (${reason}). Use /goal resume to continue.`;
+}
+
+/** Paused goals use /goal resume guidance in footer attention copy. */
+export function recoveryAttentionMessage(reason: string): string {
+  return recoveryPausedAttentionMessage(reason);
+}

package/src/runtime-config.ts

@@ -0,0 +1,7 @@
+export const CONTINUATION_RETRY_MS = 50;
+export const RUNTIME_PERSIST_INTERVAL_MS = 60_000;
+
+export const __testHooks = {
+  continuationRetryMs: CONTINUATION_RETRY_MS,
+  runtimePersistIntervalMs: RUNTIME_PERSIST_INTERVAL_MS,
+};

package/src/stale-queued-work-guard.ts

@@ -0,0 +1,114 @@
+import {
+  createInitialStaleQueuedWorkState,
+  lifecycleKindFromState,
+  reduceStaleQueuedWork,
+  type AgentEndMessage,
+  type StaleQueuedWorkEffect,
+  type StaleQueuedWorkEvent,
+  type StaleQueuedWorkLifecycleKind,
+  type StaleQueuedWorkPlan,
+  type StaleQueuedWorkState,
+} from "./stale-queued-work-reducer.js";
+
+export type {
+  AgentEndMessage,
+  StaleQueuedWorkEffect,
+  StaleQueuedWorkLifecycleKind,
+  StaleQueuedWorkPlan,
+} from "./stale-queued-work-reducer.js";
+
+export interface StaleQueuedWorkGuard {
+  lifecycleKind(): StaleQueuedWorkLifecycleKind;
+  isBlockingContinuation(): boolean;
+  noteRunnableWorkStarted(): void;
+  noteStaleWorkStarted(goalId: string): void;
+  planContextAbort(currentTurnIndex: number | null): StaleQueuedWorkPlan | null;
+  planUserInputClearAbort(): StaleQueuedWorkPlan;
+  planExtensionContinuationClearAbort(): StaleQueuedWorkPlan;
+  planBeforeAgentStartClearAbort(): StaleQueuedWorkPlan;
+  planTurnStart(): StaleQueuedWorkPlan;
+  planToolExecutionEnd(): StaleQueuedWorkPlan;
+  planSessionBeforeCompact(): StaleQueuedWorkPlan;
+  planSessionCompact(): StaleQueuedWorkPlan;
+  planTurnEnd(turnIndex: number | null): StaleQueuedWorkPlan;
+  planAgentEnd(messages: AgentEndMessage[]): StaleQueuedWorkPlan;
+  planSessionShutdown(): StaleQueuedWorkPlan;
+}
+
+function emptyPlan(): StaleQueuedWorkPlan {
+  return { skip: false, effects: [] };
+}
+
+export function createStaleQueuedWorkGuard(): StaleQueuedWorkGuard {
+  let state: StaleQueuedWorkState = createInitialStaleQueuedWorkState();
+
+  const dispatch = (event: StaleQueuedWorkEvent): StaleQueuedWorkPlan | null => {
+    const result = reduceStaleQueuedWork(state, event);
+    state = result.state;
+    return result.plan;
+  };
+
+  const plan = (event: StaleQueuedWorkEvent): StaleQueuedWorkPlan => dispatch(event) ?? emptyPlan();
+
+  return {
+    lifecycleKind(): StaleQueuedWorkLifecycleKind {
+      return lifecycleKindFromState(state);
+    },
+
+    isBlockingContinuation(): boolean {
+      return state.kind === "abortingTurn";
+    },
+
+    noteRunnableWorkStarted(): void {
+      dispatch({ type: "runnableWorkStarted" });
+    },
+
+    noteStaleWorkStarted(goalId: string): void {
+      dispatch({ type: "staleWorkStarted", goalId });
+    },
+
+    planContextAbort(currentTurnIndex: number | null): StaleQueuedWorkPlan | null {
+      return dispatch({ type: "contextAbort", currentTurnIndex });
+    },
+
+    planUserInputClearAbort(): StaleQueuedWorkPlan {
+      return plan({ type: "userInputClearAbort" });
+    },
+
+    planExtensionContinuationClearAbort(): StaleQueuedWorkPlan {
+      return plan({ type: "extensionContinuationClearAbort" });
+    },
+
+    planBeforeAgentStartClearAbort(): StaleQueuedWorkPlan {
+      return plan({ type: "beforeAgentStartClearAbort" });
+    },
+
+    planTurnStart(): StaleQueuedWorkPlan {
+      return plan({ type: "turnStart" });
+    },
+
+    planToolExecutionEnd(): StaleQueuedWorkPlan {
+      return plan({ type: "toolExecutionEnd" });
+    },
+
+    planSessionBeforeCompact(): StaleQueuedWorkPlan {
+      return plan({ type: "sessionBeforeCompact" });
+    },
+
+    planSessionCompact(): StaleQueuedWorkPlan {
+      return plan({ type: "sessionCompact" });
+    },
+
+    planTurnEnd(turnIndex: number | null): StaleQueuedWorkPlan {
+      return plan({ type: "turnEnd", turnIndex });
+    },
+
+    planAgentEnd(messages: AgentEndMessage[]): StaleQueuedWorkPlan {
+      return plan({ type: "agentEnd", messages });
+    },
+
+    planSessionShutdown(): StaleQueuedWorkPlan {
+      return plan({ type: "sessionShutdown" });
+    },
+  };
+}

package/src/stale-queued-work-obligations.ts

@@ -0,0 +1,291 @@
+import {
+  agentEndMessagesIncludeQueuedGoalWork,
+  pendingStaleQueuedGoalWorkIdsFromMessages,
+} from "./queued-goal-work.js";
+import type {
+  AbortingTurnState,
+  AgentEndMessage,
+  AgentEndObligation,
+  TerminalCleanup,
+  TerminalObligationPhase,
+} from "./stale-queued-work-types.js";
+
+export function obligationsForStaleAbort(
+  staleGoalIds: ReadonlySet<string>,
+  phase: TerminalObligationPhase,
+): AgentEndObligation[] {
+  if (staleGoalIds.size === 0) {
+    return [];
+  }
+  return [{ goalIds: new Set(staleGoalIds), acceptsAnonymous: true, phase }];
+}
+
+export function setAnonymousMatching(
+  obligations: AgentEndObligation[],
+  acceptsAnonymous: boolean,
+): void {
+  for (const obligation of obligations) {
+    obligation.acceptsAnonymous = acceptsAnonymous;
+  }
+}
+
+export function markAllObligationsOlder(cleanup: TerminalCleanup): void {
+  for (const obligation of cleanup.pendingAgentEndObligations) {
+    obligation.phase = "older";
+  }
+}
+
+export function dropActiveObligations(cleanup: TerminalCleanup): void {
+  cleanup.pendingAgentEndObligations = cleanup.pendingAgentEndObligations.filter(
+    (obligation) => obligation.phase !== "active",
+  );
+}
+
+export function consumePendingStaleAgentEnd(
+  cleanup: TerminalCleanup,
+  messages: AgentEndMessage[],
+): boolean {
+  const pendingGoalIds = pendingGoalIdsFromObligations(cleanup.pendingAgentEndObligations);
+  const matchedGoalIds = pendingStaleQueuedGoalWorkIdsFromMessages(messages, pendingGoalIds);
+  const goalMatch = consumeGoalBearingTerminal(
+    cleanup.pendingAgentEndObligations,
+    matchedGoalIds,
+    ["older", "active"],
+  );
+  if (goalMatch.consumed) {
+    return true;
+  }
+  if (!matchesAnonymousStaleAgentEnd(messages)) {
+    return false;
+  }
+  return consumeAnonymousTerminal(
+    cleanup.pendingAgentEndObligations,
+    ["older", "active"],
+  ).consumed;
+}
+
+export type AbortingAgentEndConsumption = {
+  consumedActive: boolean;
+  consumedOlder: boolean;
+  activePending: boolean;
+};
+
+export function consumeAbortingAgentEnd(
+  aborting: AbortingTurnState,
+  messages: AgentEndMessage[],
+): AbortingAgentEndConsumption {
+  const { terminalCleanup } = aborting;
+  const matchedGoalIds = pendingStaleQueuedGoalWorkIdsFromMessages(
+    messages,
+    allPendingGoalIds(terminalCleanup),
+  );
+  const preferActiveFirst =
+    activeTurnEndConsumed(aborting) &&
+    matchedGoalIds.length > 0 &&
+    isSubsetOfSet(matchedGoalIds, pendingGoalIdsByPhase(terminalCleanup, "active"));
+
+  const goalMatch = consumeGoalBearingTerminal(
+    terminalCleanup.pendingAgentEndObligations,
+    matchedGoalIds,
+    preferActiveFirst ? ["active", "older"] : ["older", "active"],
+  );
+
+  let consumedActive = goalMatch.consumedActive;
+  let consumedOlder = goalMatch.consumedOlder;
+  if (matchesAnonymousStaleAgentEnd(messages)) {
+    const preferActiveAnonymous =
+      activeTurnEndConsumed(aborting) &&
+      terminalCleanup.pendingAgentEndObligations.some(
+        (obligation) => obligation.phase === "active" && obligation.acceptsAnonymous,
+      );
+    const anonymousMatch = consumeAnonymousTerminalForAbortingTurn(
+      terminalCleanup.pendingAgentEndObligations,
+      preferActiveAnonymous ? ["active", "older"] : ["older", "active"],
+    );
+    consumedActive ||= anonymousMatch.consumedActive;
+    consumedOlder ||= anonymousMatch.consumedOlder;
+  }
+
+  return {
+    consumedActive,
+    consumedOlder,
+    activePending: terminalCleanup.pendingAgentEndObligations.some(
+      (obligation) => obligation.phase === "active",
+    ),
+  };
+}
+
+function isStaleTerminalAssistantMessage(message: { role: string; stopReason?: string }): boolean {
+  return (
+    message.role === "assistant" &&
+    (message.stopReason === "aborted" ||
+      message.stopReason === "stop" ||
+      message.stopReason === "error")
+  );
+}
+
+function matchesAnonymousStaleAgentEnd(messages: AgentEndMessage[]): boolean {
+  if (agentEndMessagesIncludeQueuedGoalWork(messages)) {
+    return false;
+  }
+  return messages.some(isStaleTerminalAssistantMessage);
+}
+
+function activeTurnEndConsumed(aborting: AbortingTurnState): boolean {
+  const { activeTurnIndex, terminalCleanup } = aborting;
+  return activeTurnIndex !== null && !terminalCleanup.pendingTurnEndIndexes.has(activeTurnIndex);
+}
+
+function allPendingGoalIds(cleanup: TerminalCleanup): Set<string> {
+  return pendingGoalIdsFromObligations(cleanup.pendingAgentEndObligations);
+}
+
+function pendingGoalIdsByPhase(
+  cleanup: TerminalCleanup,
+  phase: TerminalObligationPhase,
+): Set<string> {
+  return pendingGoalIdsFromObligations(
+    cleanup.pendingAgentEndObligations.filter((obligation) => obligation.phase === phase),
+  );
+}
+
+function pendingGoalIdsFromObligations(obligations: readonly AgentEndObligation[]): Set<string> {
+  const goalIds = new Set<string>();
+  for (const obligation of obligations) {
+    for (const goalId of obligation.goalIds) {
+      goalIds.add(goalId);
+    }
+  }
+  return goalIds;
+}
+
+function isSubsetOfSet(values: readonly string[], superset: ReadonlySet<string>): boolean {
+  for (const value of values) {
+    if (!superset.has(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function obligationMatchesAnyGoal(
+  obligation: AgentEndObligation,
+  matchedGoalIds: ReadonlySet<string>,
+): boolean {
+  for (const goalId of obligation.goalIds) {
+    if (matchedGoalIds.has(goalId)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+type ConsumptionResult = {
+  consumed: boolean;
+  consumedOlder: boolean;
+  consumedActive: boolean;
+};
+
+function emptyConsumptionResult(): ConsumptionResult {
+  return { consumed: false, consumedOlder: false, consumedActive: false };
+}
+
+function recordConsumedObligation(result: ConsumptionResult, obligation: AgentEndObligation): void {
+  result.consumed = true;
+  result.consumedOlder ||= obligation.phase === "older";
+  result.consumedActive ||= obligation.phase === "active";
+}
+
+function consumeObligationAt(
+  obligations: AgentEndObligation[],
+  index: number,
+): AgentEndObligation | null {
+  const [obligation] = obligations.splice(index, 1);
+  return obligation ?? null;
+}
+
+function consumeGoalBearingTerminal(
+  obligations: AgentEndObligation[],
+  matchedGoalIds: readonly string[],
+  phaseOrder: readonly TerminalObligationPhase[],
+): ConsumptionResult {
+  const result = emptyConsumptionResult();
+  const remainingGoalIds = new Set(matchedGoalIds);
+
+  for (const phase of phaseOrder) {
+    for (let index = 0; index < obligations.length; ) {
+      const obligation = obligations[index]!;
+      if (
+        obligation.phase !== phase ||
+        remainingGoalIds.size === 0 ||
+        !obligationMatchesAnyGoal(obligation, remainingGoalIds)
+      ) {
+        index += 1;
+        continue;
+      }
+
+      const consumed = consumeObligationAt(obligations, index);
+      if (consumed) {
+        recordConsumedObligation(result, consumed);
+        for (const goalId of consumed.goalIds) {
+          remainingGoalIds.delete(goalId);
+        }
+      }
+      if (remainingGoalIds.size === 0) {
+        return result;
+      }
+    }
+  }
+
+  return result;
+}
+
+function consumeAnonymousTerminal(
+  obligations: AgentEndObligation[],
+  phaseOrder: readonly TerminalObligationPhase[],
+): ConsumptionResult {
+  const result = emptyConsumptionResult();
+
+  for (const phase of phaseOrder) {
+    for (let index = 0; index < obligations.length; index += 1) {
+      const obligation = obligations[index]!;
+      if (obligation.phase !== phase || !obligation.acceptsAnonymous) {
+        continue;
+      }
+
+      const consumed = consumeObligationAt(obligations, index);
+      if (consumed) {
+        recordConsumedObligation(result, consumed);
+      }
+      return result;
+    }
+  }
+
+  return result;
+}
+
+function consumeAnonymousTerminalForAbortingTurn(
+  obligations: AgentEndObligation[],
+  phaseOrder: readonly TerminalObligationPhase[],
+): ConsumptionResult {
+  const result = emptyConsumptionResult();
+  const fallbackPhase = phaseOrder.at(-1);
+
+  for (const phase of phaseOrder) {
+    for (let index = 0; index < obligations.length; index += 1) {
+      const obligation = obligations[index]!;
+      const matchesCurrentAbort = obligation.acceptsAnonymous || phase === fallbackPhase;
+      if (obligation.phase !== phase || !matchesCurrentAbort) {
+        continue;
+      }
+
+      const consumed = consumeObligationAt(obligations, index);
+      if (consumed) {
+        recordConsumedObligation(result, consumed);
+      }
+      return result;
+    }
+  }
+
+  return result;
+}