@kky42/pi-goal 1.0.0

package/src/queued-goal-messages.ts

@@ -0,0 +1,166 @@
+import { CUSTOM_ENTRY_TYPE } from "./types.js";
+
+type GoalQueuedWorkKind = "continuation" | "command_start" | "command_resume";
+
+export interface ActiveGoalQueuedDetails {
+  kind: GoalQueuedWorkKind;
+  goalId: string;
+}
+
+export interface QueuedGoalTextPart {
+  readonly type: "text";
+  readonly text: string;
+}
+
+export type QueuedGoalUserContent = QueuedGoalTextPart[];
+
+/** External provider-context message shape before normalization. */
+export interface QueuedGoalContextInput {
+  role: string;
+  customType?: string;
+  content?: unknown;
+  display?: boolean;
+  details?: unknown;
+  timestamp?: number;
+}
+
+/** Normalized provider-context carrier with required runtime fields. */
+export interface QueuedGoalContextCarrier {
+  role: string;
+  timestamp: number;
+  customType?: string;
+  content?: unknown;
+  display?: boolean;
+  details?: unknown;
+}
+
+export interface QueuedGoalCustomMessage extends QueuedGoalContextCarrier {
+  role: "custom";
+  customType: typeof CUSTOM_ENTRY_TYPE;
+  content: string | QueuedGoalUserContent;
+  display: boolean;
+}
+
+export interface QueuedGoalUserMessage extends QueuedGoalContextCarrier {
+  role: "user";
+  content: QueuedGoalUserContent;
+}
+
+export type QueuedGoalWorkSourceMessage = QueuedGoalCustomMessage | QueuedGoalUserMessage;
+
+/** Role/customType only — does not prove normalized content or display. */
+interface QueuedGoalCustomRoleCarrier {
+  role: "custom";
+  customType: typeof CUSTOM_ENTRY_TYPE;
+}
+
+function isQueuedGoalCustomRole(
+  message: QueuedGoalContextCarrier,
+): message is QueuedGoalContextCarrier & QueuedGoalCustomRoleCarrier {
+  return message.role === "custom" && message.customType === CUSTOM_ENTRY_TYPE;
+}
+
+export function userContentFromUnknown(content: unknown): QueuedGoalUserContent {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  const parts: QueuedGoalTextPart[] = [];
+  for (const part of content) {
+    if (part === null || typeof part !== "object") {
+      continue;
+    }
+    const candidate = part as { type?: unknown; text?: unknown };
+    if (candidate.type === "text" && typeof candidate.text === "string") {
+      parts.push({ type: "text", text: candidate.text });
+    }
+  }
+  return parts;
+}
+
+function customContentFromUnknown(content: unknown): string | QueuedGoalUserContent {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  const normalized = userContentFromUnknown(content);
+  return normalized.length > 0 ? normalized : "";
+}
+
+/** Copies provider-context fields into a carrier with the runtime-required timestamp. */
+export function toQueuedGoalContextCarrier(message: QueuedGoalContextInput): QueuedGoalContextCarrier | null {
+  if (typeof message.timestamp !== "number") {
+    return null;
+  }
+
+  const carrier: QueuedGoalContextCarrier = {
+    role: message.role,
+    timestamp: message.timestamp,
+  };
+  if (message.customType !== undefined) {
+    carrier.customType = message.customType;
+  }
+  if (message.content !== undefined) {
+    carrier.content = message.content;
+  }
+  if (message.display !== undefined) {
+    carrier.display = message.display;
+  }
+  if (message.details !== undefined) {
+    carrier.details = message.details;
+  }
+  return carrier;
+}
+
+/** Narrows a carrier to queued-goal user/custom work and normalizes its content. */
+export function toQueuedGoalWorkSource(
+  message: QueuedGoalContextCarrier,
+): QueuedGoalWorkSourceMessage | null {
+  switch (message.role) {
+    case "user":
+      return {
+        ...message,
+        role: "user",
+        content: userContentFromUnknown(message.content),
+      };
+    case "custom": {
+      if (!isQueuedGoalCustomRole(message)) {
+        return null;
+      }
+      const normalized: QueuedGoalCustomMessage = {
+        role: "custom",
+        customType: message.customType,
+        timestamp: message.timestamp,
+        content: customContentFromUnknown(message.content),
+        display: message.display ?? false,
+      };
+      if (message.details !== undefined) {
+        normalized.details = message.details;
+      }
+      return normalized;
+    }
+    default:
+      return null;
+  }
+}
+
+export function isActiveGoalQueuedDetails(details: unknown): details is ActiveGoalQueuedDetails {
+  if (details === null || typeof details !== "object") {
+    return false;
+  }
+
+  const candidate = details as { kind?: unknown; goalId?: unknown };
+  const kind = candidate.kind;
+  return (
+    (kind === "continuation" || kind === "command_start" || kind === "command_resume") &&
+    typeof candidate.goalId === "string"
+  );
+}
+
+export function isCommandResumeQueuedGoalMessage(message: QueuedGoalContextCarrier): boolean {
+  return (
+    isQueuedGoalCustomRole(message) &&
+    isActiveGoalQueuedDetails(message.details) &&
+    message.details.kind === "command_resume"
+  );
+}

package/src/queued-goal-work.ts

@@ -0,0 +1,96 @@
+import { continuationGoalIdFromPrompt } from "./prompts.js";
+import {
+  isActiveGoalQueuedDetails,
+  type QueuedGoalContextInput,
+  userContentFromUnknown,
+} from "./queued-goal-messages.js";
+import { CUSTOM_ENTRY_TYPE, type ThreadGoal } from "./types.js";
+
+function isSupersededContinuationDetails(details: unknown): boolean {
+  return details !== null && typeof details === "object" && (details as { kind?: unknown }).kind === "superseded_continuation";
+}
+
+function textContentFromMessageContent(content: unknown): string | null {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  const parts = userContentFromUnknown(content);
+  if (parts.length === 0) {
+    return null;
+  }
+
+  return parts.map((part) => part.text).join("\n");
+}
+
+function continuationGoalIdFromMessageContent(content: unknown): string | null {
+  const text = textContentFromMessageContent(content);
+  return text === null ? null : continuationGoalIdFromPrompt(text);
+}
+
+export function extensionQueuedGoalWorkMessageId(message: QueuedGoalContextInput): string | null {
+  if (message.role !== "custom" || message.customType !== CUSTOM_ENTRY_TYPE) {
+    return null;
+  }
+
+  if (isSupersededContinuationDetails(message.details)) {
+    return null;
+  }
+
+  if (isActiveGoalQueuedDetails(message.details)) {
+    return message.details.goalId;
+  }
+
+  return continuationGoalIdFromMessageContent(message.content);
+}
+
+function queuedGoalWorkMessageId(message: QueuedGoalContextInput): string | null {
+  if (message.role === "user") {
+    return continuationGoalIdFromMessageContent(message.content);
+  }
+
+  return extensionQueuedGoalWorkMessageId(message);
+}
+
+export function applyQueuedGoalProviderContextRewrites<TMessage extends QueuedGoalContextInput>(
+  messages: readonly TMessage[],
+  _options: {
+    goal: ThreadGoal | null;
+    resolveStaleQueuedGoalWorkMessageId: (message: QueuedGoalContextInput) => string | null;
+    resolveActiveContinuationQueuedGoalWorkMessageId: (message: QueuedGoalContextInput) => string | null;
+  },
+): { messages: TMessage[]; changed: boolean } {
+  return { messages: [...messages], changed: false };
+}
+
+export function extensionQueuedGoalWorkMessageIdForRuntime(
+  message: QueuedGoalContextInput,
+  resolveContinuationGoalIdFromPrompt: (prompt: string) => string | null,
+): string | null {
+  if (message.role === "user") {
+    const text = textContentFromMessageContent(message.content);
+    return text === null ? null : resolveContinuationGoalIdFromPrompt(text);
+  }
+
+  return queuedGoalWorkMessageId(message);
+}
+
+export function agentEndMessagesIncludeQueuedGoalWork(
+  messages: readonly QueuedGoalContextInput[],
+): boolean {
+  return messages.some((message) => queuedGoalWorkMessageId(message) !== null);
+}
+
+export function pendingStaleQueuedGoalWorkIdsFromMessages(
+  messages: readonly QueuedGoalContextInput[],
+  staleQueuedGoalWorkAgentEndGoalIds: ReadonlySet<string>,
+): string[] {
+  const goalIds: string[] = [];
+  for (const message of messages) {
+    const queuedGoalId = queuedGoalWorkMessageId(message);
+    if (queuedGoalId !== null && staleQueuedGoalWorkAgentEndGoalIds.has(queuedGoalId)) {
+      goalIds.push(queuedGoalId);
+    }
+  }
+  return goalIds;
+}

package/src/recovery-adapters.ts

@@ -0,0 +1,66 @@
+import type { AssistantMessage, StopReason } from "@earendil-works/pi-ai";
+
+export interface OverflowCheckAssistantMessage {
+  stopReason?: string;
+  errorMessage?: string;
+  usage?: {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+}
+
+const OVERFLOW_CHECK_API = "pi-codex-goal-overflow-check";
+const OVERFLOW_CHECK_PROVIDER = "pi-codex-goal";
+const OVERFLOW_CHECK_MODEL = "overflow-check";
+
+function stopReasonFromAssistantError(stopReason: string | undefined): StopReason {
+  switch (stopReason) {
+    case "stop":
+    case "length":
+    case "toolUse":
+    case "error":
+    case "aborted":
+      return stopReason;
+    default:
+      return "error";
+  }
+}
+
+/** Single adapter for pi-ai overflow checks; keeps AssistantMessage casts out of recovery logic. */
+export function assistantMessageForOverflowCheck(message: OverflowCheckAssistantMessage): AssistantMessage {
+  const usage = message.usage ?? { input: 0, output: 0 };
+  const cacheRead = usage.cacheRead ?? 0;
+  const cacheWrite = usage.cacheWrite ?? 0;
+
+  const assistantMessage: AssistantMessage = {
+    role: "assistant",
+    content: [],
+    api: OVERFLOW_CHECK_API,
+    provider: OVERFLOW_CHECK_PROVIDER,
+    model: OVERFLOW_CHECK_MODEL,
+    usage: {
+      input: usage.input,
+      output: usage.output,
+      cacheRead,
+      cacheWrite,
+      totalTokens: usage.input + usage.output + cacheRead + cacheWrite,
+      cost: {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        total: 0,
+      },
+    },
+    stopReason: stopReasonFromAssistantError(message.stopReason),
+    timestamp: 0,
+  };
+
+  if (message.errorMessage !== undefined) {
+    assistantMessage.errorMessage = message.errorMessage;
+  }
+
+  return assistantMessage;
+}

package/src/recovery-machine.ts

@@ -0,0 +1,196 @@
+import {
+  applyPersistedHostOverflowUserReset,
+  clearHostOverflowRecoveryActive,
+  hostOverflowRecoveringNeedsUserStartPhase,
+  idleRecoveryPhase,
+  recoveryPhaseNeedsUserStartTurn,
+  type RecoveryPhase,
+} from "./recovery-phase.js";
+import {
+  CONTEXT_OVERFLOW_SIGNATURE,
+  countersForFailureSignature,
+  createErrorRecoveryCounters,
+  failureSignature,
+  HOST_OVERFLOW_RECOVERY_REASON,
+  isContextOverflowError,
+  isRetryableTransientError,
+  isSuccessfulAssistantTurn,
+  MAX_CONTEXT_COMPACTION_RETRIES,
+  recoveryPausedAttentionMessage,
+  recoveryPendingAttentionMessage,
+  type AssistantErrorMessage,
+  type ErrorRecoveryCounters,
+} from "./recovery.js";
+
+export type { GoalStartTurnStrategy, RecoveryPhase } from "./recovery-phase.js";
+export {
+  goalStartTurnStrategy,
+  recoveryPhaseBlocksContinuation,
+  recoveryPhaseNeedsUserStartTurn,
+} from "./recovery-phase.js";
+
+export type RecoveryAction =
+  | { type: "noop" }
+  | { type: "pending"; reason: string }
+  | { type: "pause"; reason: string };
+
+export interface GoalRecoveryMachineState {
+  counters: ErrorRecoveryCounters;
+  attention: string | null;
+  phase: RecoveryPhase;
+}
+
+export function createGoalRecoveryMachine(): GoalRecoveryMachineState {
+  return {
+    counters: createErrorRecoveryCounters(),
+    attention: null,
+    phase: idleRecoveryPhase,
+  };
+}
+
+export function resetRecoveryMachine(state: GoalRecoveryMachineState): void {
+  state.counters = createErrorRecoveryCounters();
+  state.attention = null;
+  clearActiveHostOverflowRecovery(state);
+}
+
+export function resetRecoveryCounters(state: GoalRecoveryMachineState): void {
+  state.counters = createErrorRecoveryCounters();
+  state.attention = null;
+}
+
+export function onRecoveryUserInput(state: GoalRecoveryMachineState): void {
+  resetRecoveryMachine(state);
+}
+
+export function onRecoverySuccessfulTurn(
+  state: GoalRecoveryMachineState,
+  message: AssistantErrorMessage,
+): boolean {
+  if (!isSuccessfulAssistantTurn(message)) {
+    return false;
+  }
+  resetRecoveryCounters(state);
+  return true;
+}
+
+export function onRecoverySessionCompact(state: GoalRecoveryMachineState): void {
+  if (state.attention === recoveryPendingAttentionMessage(HOST_OVERFLOW_RECOVERY_REASON)) {
+    state.attention = null;
+  }
+
+  if (state.counters.compactionAttempts > 0) {
+    state.counters = {
+      ...state.counters,
+      transientAttempts: 0,
+    };
+  }
+}
+
+export function setRecoveryPendingAttention(state: GoalRecoveryMachineState, reason: string): string {
+  const message = recoveryPendingAttentionMessage(reason);
+  state.attention = message;
+  return message;
+}
+
+export function setRecoveryPausedAttention(state: GoalRecoveryMachineState, reason: string): string {
+  const message = recoveryPausedAttentionMessage(reason);
+  state.attention = message;
+  return message;
+}
+
+export function clearActiveHostOverflowRecovery(state: GoalRecoveryMachineState): void {
+  state.phase = clearHostOverflowRecoveryActive(state.phase);
+}
+
+export function applyHostOverflowUserResetPersistence(
+  state: GoalRecoveryMachineState,
+  needsUserReset: boolean,
+): boolean {
+  if (recoveryPhaseNeedsUserStartTurn(state.phase) === needsUserReset) {
+    return false;
+  }
+  state.phase = applyPersistedHostOverflowUserReset(state.phase, needsUserReset);
+  return true;
+}
+
+export function syncHostOverflowUserResetFromSession(
+  state: GoalRecoveryMachineState,
+  needsUserReset: boolean,
+): void {
+  state.phase = applyPersistedHostOverflowUserReset(state.phase, needsUserReset);
+}
+
+/** Session-level overflow: require a user-started goal turn even without an active goal. */
+export function requireHostOverflowUserReset(state: GoalRecoveryMachineState): boolean {
+  const persistHostOverflowCapReset = !recoveryPhaseNeedsUserStartTurn(state.phase);
+  state.phase = applyPersistedHostOverflowUserReset(state.phase, true);
+  return persistHostOverflowCapReset;
+}
+
+export function beginHostOverflowRecovery(state: GoalRecoveryMachineState): {
+  attention: string;
+  persistHostOverflowCapReset: boolean;
+} {
+  const persistHostOverflowCapReset = !recoveryPhaseNeedsUserStartTurn(state.phase);
+  state.phase = hostOverflowRecoveringNeedsUserStartPhase();
+  const attention = setRecoveryPendingAttention(state, HOST_OVERFLOW_RECOVERY_REASON);
+  return { attention, persistHostOverflowCapReset };
+}
+
+function incrementOverflowCompactionAttempts(state: GoalRecoveryMachineState): RecoveryAction {
+  state.counters = {
+    ...state.counters,
+    signature: CONTEXT_OVERFLOW_SIGNATURE,
+    compactionAttempts: state.counters.compactionAttempts + 1,
+  };
+  if (state.counters.compactionAttempts > MAX_CONTEXT_COMPACTION_RETRIES) {
+    return {
+      type: "pause",
+      reason: "context window recovery failed after repeated compaction attempts",
+    };
+  }
+  return { type: "noop" };
+}
+
+/**
+ * Plans extension recovery only after pi host post-run retry/compaction has finished.
+ * Host AgentSession._handlePostAgentRun() owns retry and overflow compaction; this
+ * extension tracks persistent failures and pauses with attention when caps are exceeded.
+ */
+export function planRecoveryForAssistantError(
+  state: GoalRecoveryMachineState,
+  message: AssistantErrorMessage,
+): RecoveryAction {
+  if (isContextOverflowError(message.errorMessage)) {
+    return incrementOverflowCompactionAttempts(state);
+  }
+
+  const signature = failureSignature(message.errorMessage);
+  state.counters = countersForFailureSignature(state.counters, signature);
+
+  if (!isRetryableTransientError(message.errorMessage)) {
+    return {
+      type: "pause",
+      reason: `non-retryable provider error (${signature})`,
+    };
+  }
+
+  state.counters = {
+    ...state.counters,
+    transientAttempts: state.counters.transientAttempts + 1,
+  };
+  return {
+    type: "pending",
+    reason: `provider error (${signature})`,
+  };
+}
+
+export function planRecoveryForSilentContextOverflow(state: GoalRecoveryMachineState): RecoveryAction {
+  return incrementOverflowCompactionAttempts(state);
+}
+
+/** True when another overflow in this recovery cycle would exceed the compaction cap. */
+export function isRepeatOverflowCompactionDue(state: GoalRecoveryMachineState): boolean {
+  return state.counters.compactionAttempts >= MAX_CONTEXT_COMPACTION_RETRIES;
+}

package/src/recovery-phase.ts

@@ -0,0 +1,95 @@
+export type RecoveryPhase =
+  | { kind: "idle" }
+  | { kind: "hostOverflowRecoveringNeedsUserStart" }
+  | { kind: "hostOverflowRecovering" }
+  | { kind: "hostOverflowNeedsUserStart" };
+
+export type GoalStartTurnStrategy = "hiddenFollowUp" | "userFollowUp";
+
+export const idleRecoveryPhase: RecoveryPhase = { kind: "idle" };
+
+function assertNever(value: never): never {
+  throw new Error(`Unexpected recovery phase: ${JSON.stringify(value)}`);
+}
+
+export function recoveryPhaseNeedsUserStartTurn(phase: RecoveryPhase): boolean {
+  switch (phase.kind) {
+    case "idle":
+    case "hostOverflowRecovering":
+      return false;
+    case "hostOverflowRecoveringNeedsUserStart":
+    case "hostOverflowNeedsUserStart":
+      return true;
+    default:
+      return assertNever(phase);
+  }
+}
+
+export function goalStartTurnStrategy(phase: RecoveryPhase): GoalStartTurnStrategy {
+  return recoveryPhaseNeedsUserStartTurn(phase) ? "userFollowUp" : "hiddenFollowUp";
+}
+
+export function recoveryPhaseBlocksContinuation(phase: RecoveryPhase): boolean {
+  switch (phase.kind) {
+    case "idle":
+    case "hostOverflowNeedsUserStart":
+      return false;
+    case "hostOverflowRecoveringNeedsUserStart":
+    case "hostOverflowRecovering":
+      return true;
+    default:
+      return assertNever(phase);
+  }
+}
+
+export function hostOverflowRecoveringNeedsUserStartPhase(): RecoveryPhase {
+  return { kind: "hostOverflowRecoveringNeedsUserStart" };
+}
+
+export function clearHostOverflowRecoveryActive(phase: RecoveryPhase): RecoveryPhase {
+  switch (phase.kind) {
+    case "hostOverflowRecoveringNeedsUserStart":
+      return { kind: "hostOverflowNeedsUserStart" };
+    case "hostOverflowRecovering":
+      return idleRecoveryPhase;
+    case "idle":
+    case "hostOverflowNeedsUserStart":
+      return phase;
+    default:
+      return assertNever(phase);
+  }
+}
+
+export function clearHostOverflowUserReset(phase: RecoveryPhase): RecoveryPhase {
+  switch (phase.kind) {
+    case "hostOverflowRecoveringNeedsUserStart":
+      return { kind: "hostOverflowRecovering" };
+    case "hostOverflowNeedsUserStart":
+      return idleRecoveryPhase;
+    case "idle":
+    case "hostOverflowRecovering":
+      return phase;
+    default:
+      return assertNever(phase);
+  }
+}
+
+export function applyPersistedHostOverflowUserReset(
+  phase: RecoveryPhase,
+  needsUserReset: boolean,
+): RecoveryPhase {
+  if (!needsUserReset) {
+    return clearHostOverflowUserReset(phase);
+  }
+  switch (phase.kind) {
+    case "hostOverflowRecovering":
+      return { kind: "hostOverflowRecoveringNeedsUserStart" };
+    case "hostOverflowRecoveringNeedsUserStart":
+    case "hostOverflowNeedsUserStart":
+      return phase;
+    case "idle":
+      return { kind: "hostOverflowNeedsUserStart" };
+    default:
+      return assertNever(phase);
+  }
+}