@kky42/pi-goal 1.0.0

package/src/format.ts

@@ -0,0 +1,232 @@
+import type { GoalStatus, ThreadGoal } from "./types.js";
+
+const COMPACT_TOKEN_UNITS = [
+  { suffix: "T", value: 1_000_000_000_000 },
+  { suffix: "B", value: 1_000_000_000 },
+  { suffix: "M", value: 1_000_000 },
+  { suffix: "K", value: 1_000 },
+] as const;
+
+export interface GoalToolRecord {
+  objective: string;
+  status: GoalStatus;
+  tokenBudget: number | null;
+  tokensUsed: number;
+  timeUsed: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface GoalToolResponse {
+  goal: GoalToolRecord | null;
+  remainingTokens: number | null;
+  completionBudgetReport: string | null;
+}
+
+export function formatDuration(seconds: number): string {
+  const normalized = Math.max(0, Math.trunc(seconds));
+  const hours = Math.floor(normalized / 3_600);
+  const minutes = Math.floor((normalized % 3_600) / 60);
+  const remainingSeconds = normalized % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${remainingSeconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${remainingSeconds}s`;
+  }
+  return `${remainingSeconds}s`;
+}
+
+function twoDigit(value: number): string {
+  return String(value).padStart(2, "0");
+}
+
+export function formatLocalTimestamp(unixSeconds: number): string {
+  const date = new Date(Math.max(0, Math.trunc(unixSeconds)) * 1000);
+  const day = `${date.getFullYear()}-${twoDigit(date.getMonth() + 1)}-${twoDigit(date.getDate())}`;
+  const time = `${twoDigit(date.getHours())}-${twoDigit(date.getMinutes())}-${twoDigit(date.getSeconds())}`;
+  return `${day} ${time}`;
+}
+
+export function formatInteger(value: number): string {
+  return Math.max(0, Math.trunc(value)).toLocaleString("en-US");
+}
+
+export function formatCompactTokenValue(value: number): string {
+  const normalized = Math.max(0, Math.trunc(value));
+  if (normalized < 100_000) {
+    return formatInteger(normalized);
+  }
+
+  const unit = COMPACT_TOKEN_UNITS.find((candidate) => normalized >= candidate.value);
+  if (!unit) {
+    return formatInteger(normalized);
+  }
+
+  const scaled = normalized / unit.value;
+  const fractionDigits = scaled < 10 ? 2 : scaled < 100 ? 1 : 0;
+  const compact = scaled.toLocaleString("en-US", {
+    maximumFractionDigits: fractionDigits,
+    minimumFractionDigits: 0,
+  });
+  return `${compact}${unit.suffix}`;
+}
+
+export function formatTokenValue(value: number): string {
+  const exact = formatInteger(value);
+  const compact = formatCompactTokenValue(value);
+  if (compact === exact) {
+    return exact;
+  }
+  return `${compact} (${exact})`;
+}
+
+export function formatBudget(goal: ThreadGoal): string {
+  if (goal.tokenBudget === null) {
+    return `${formatTokenValue(goal.usage.tokensUsed)} tokens`;
+  }
+  return `${formatTokenValue(goal.usage.tokensUsed)}/${formatTokenValue(goal.tokenBudget)} tokens`;
+}
+
+function statusLabel(status: GoalStatus): string {
+  return status === "budgetLimited" ? "limited by budget" : status;
+}
+
+function commandHint(status: GoalStatus): string {
+  if (status === "active") {
+    return "/goal pause, /goal clear";
+  }
+  if (status === "paused") {
+    return "/goal resume, /goal clear";
+  }
+  if (status === "blocked") {
+    return "/goal resume, /goal clear";
+  }
+  if (status === "complete") {
+    return "/goal <objective> to replace, /goal clear";
+  }
+  return "/goal clear";
+}
+
+export function formatGoalSummary(goal: ThreadGoal | null): string {
+  if (!goal) {
+    return ["Usage: /goal <objective>", "No goal is currently set."].join("\n");
+  }
+
+  const lines = [
+    `Status: ${statusLabel(goal.status)}`,
+    `Objective: ${goal.objective}`,
+    `Time used: ${formatDuration(goal.usage.activeSeconds)}`,
+    `Tokens used: ${formatTokenValue(goal.usage.tokensUsed)}`,
+  ];
+
+  if (goal.tokenBudget !== null) {
+    lines.push(`Token budget: ${formatTokenValue(goal.tokenBudget)}`);
+  }
+
+  lines.push(`Hint: ${commandHint(goal.status)}`);
+  return lines.join("\n");
+}
+
+function compactBudgetUsage(goal: ThreadGoal): string {
+  if (goal.tokenBudget === null) {
+    return `${formatCompactTokenValue(goal.usage.tokensUsed)} tokens`;
+  }
+  return `${formatCompactTokenValue(goal.usage.tokensUsed)} / ${formatCompactTokenValue(goal.tokenBudget)}`;
+}
+
+export function formatFooterStatus(goal: ThreadGoal | null, recoveryAttention: string | null = null): string | undefined {
+  if (!goal) {
+    return undefined;
+  }
+
+  if (goal.status === "budgetLimited") {
+    if (goal.tokenBudget !== null) {
+      return `Goal unmet (${compactBudgetUsage(goal)} tokens)`;
+    }
+    return "Goal abandoned";
+  }
+
+  if (recoveryAttention) {
+    return recoveryAttention;
+  }
+
+  if (goal.status === "active") {
+    if (goal.tokenBudget !== null) {
+      return `Pursuing goal (${compactBudgetUsage(goal)})`;
+    }
+    if (goal.usage.activeSeconds > 0) {
+      return `Pursuing goal (${formatDuration(goal.usage.activeSeconds)})`;
+    }
+    return "Pursuing goal";
+  }
+
+  if (goal.status === "paused") {
+    return "Goal paused (/goal resume)";
+  }
+
+  if (goal.status === "blocked") {
+    return "Goal blocked (/goal resume)";
+  }
+
+  if (goal.tokenBudget !== null) {
+    return `Goal achieved (${formatCompactTokenValue(goal.usage.tokensUsed)} tokens)`;
+  }
+  if (goal.usage.activeSeconds > 0) {
+    return `Goal achieved (${formatDuration(goal.usage.activeSeconds)})`;
+  }
+  return "Goal achieved";
+}
+
+export function toToolGoal(goal: ThreadGoal): GoalToolRecord {
+  return {
+    objective: goal.objective,
+    status: goal.status,
+    tokenBudget: goal.tokenBudget,
+    tokensUsed: goal.usage.tokensUsed,
+    timeUsed: formatDuration(goal.usage.activeSeconds),
+    createdAt: formatLocalTimestamp(goal.createdAt),
+    updatedAt: formatLocalTimestamp(goal.updatedAt),
+  };
+}
+
+export function remainingTokens(goal: ThreadGoal | null): number | null {
+  if (!goal || goal.tokenBudget === null) {
+    return null;
+  }
+  return Math.max(0, goal.tokenBudget - goal.usage.tokensUsed);
+}
+
+export function completionBudgetReport(goal: ThreadGoal | null): string | null {
+  if (!goal || goal.status !== "complete") {
+    return null;
+  }
+  if (goal.tokenBudget === null && goal.usage.activeSeconds <= 0) {
+    return null;
+  }
+
+  const parts: string[] = [];
+  if (goal.usage.activeSeconds > 0) {
+    parts.push(`time used: ${formatDuration(goal.usage.activeSeconds)}.`);
+  }
+  if (goal.tokenBudget !== null) {
+    parts.push(`tokens used: ${formatInteger(goal.usage.tokensUsed)} of ${formatInteger(goal.tokenBudget)}.`);
+  } else if (goal.usage.tokensUsed > 0) {
+    parts.push(`tokens used: ${formatInteger(goal.usage.tokensUsed)}.`);
+  }
+
+  return `Goal achieved. Report final budget usage to the user: ${parts.join(" ")}`;
+}
+
+export function goalToolResponse(goal: ThreadGoal | null, includeCompletionBudgetReport = false): GoalToolResponse {
+  return {
+    goal: goal ? toToolGoal(goal) : null,
+    remainingTokens: remainingTokens(goal),
+    completionBudgetReport: includeCompletionBudgetReport ? completionBudgetReport(goal) : null,
+  };
+}
+
+export function toToolText(goal: ThreadGoal | null, includeCompletionBudgetReport = false): string {
+  return JSON.stringify(goalToolResponse(goal, includeCompletionBudgetReport), null, 2);
+}

package/src/goal-accounting.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { budgetLimitPrompt } from "./prompts.js";
+import { applyUsage } from "./state.js";
+import { CUSTOM_ENTRY_TYPE, type ThreadGoal } from "./types.js";
+
+export interface AccountingState {
+  activeGoalId: string | null;
+  lastAccountedAt: number | null;
+  budgetWarningSentFor: string | null;
+}
+
+export interface AssistantUsage {
+  input: number;
+  output: number;
+}
+
+export interface AssistantTurnMessage {
+  role: string;
+  stopReason?: string;
+  usage?: AssistantUsage;
+}
+
+export function createAccountingState(): AccountingState {
+  return {
+    activeGoalId: null,
+    lastAccountedAt: null,
+    budgetWarningSentFor: null,
+  };
+}
+
+function usageChannelTokens(value: number): number {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+
+export function assistantTurnTokens(message: AssistantTurnMessage): number {
+  if (message.role !== "assistant" || !message.usage) {
+    return 0;
+  }
+  return usageChannelTokens(message.usage.input) + usageChannelTokens(message.usage.output);
+}
+
+export function isAbortedAssistantMessage(message: AssistantTurnMessage): boolean {
+  return message.role === "assistant" && message.stopReason === "aborted";
+}
+
+export function isToolUseAssistantMessage(message: AssistantTurnMessage): boolean {
+  return message.role === "assistant" && message.stopReason === "toolUse";
+}
+
+interface GoalAccountingDeps {
+  getGoal: () => ThreadGoal | null;
+  getAccounting: () => AccountingState;
+  applyRuntimeAccountingTransition: (ctx: ExtensionContext, nextGoal: ThreadGoal) => void;
+  sendMessage: ExtensionAPI["sendMessage"];
+}
+
+export function createGoalAccounting(deps: GoalAccountingDeps) {
+  const clearActiveAccounting = (): void => {
+    const accounting = deps.getAccounting();
+    accounting.activeGoalId = null;
+    accounting.lastAccountedAt = null;
+  };
+
+  const beginAccounting = (): void => {
+    const goal = deps.getGoal();
+    const accounting = deps.getAccounting();
+    if (!goal || goal.status !== "active") {
+      accounting.activeGoalId = null;
+      accounting.lastAccountedAt = null;
+      return;
+    }
+
+    accounting.activeGoalId = goal.goalId;
+    accounting.lastAccountedAt = Date.now();
+  };
+
+  const accountProgress = (
+    ctx: ExtensionContext,
+    allowBudgetSteering: boolean,
+    completedTurnTokens = 0,
+    accountBudgetLimited = false,
+  ): void => {
+    const goal = deps.getGoal();
+    const accounting = deps.getAccounting();
+    const canAccount = goal?.status === "active" || (accountBudgetLimited && goal?.status === "budgetLimited");
+    if (!goal || accounting.activeGoalId !== goal.goalId || !canAccount) {
+      beginAccounting();
+      return;
+    }
+
+    const now = Date.now();
+    const elapsed = accounting.lastAccountedAt === null ? 0 : Math.floor((now - accounting.lastAccountedAt) / 1000);
+    accounting.lastAccountedAt = now;
+
+    const result = applyUsage(goal, completedTurnTokens, elapsed, {
+      expectedGoalId: accounting.activeGoalId,
+      accountBudgetLimited,
+    });
+    if (!result.changed || !result.goal) {
+      return;
+    }
+
+    deps.applyRuntimeAccountingTransition(ctx, result.goal);
+
+    if (allowBudgetSteering && result.crossedBudget && accounting.budgetWarningSentFor !== result.goal.goalId) {
+      accounting.budgetWarningSentFor = result.goal.goalId;
+      deps.sendMessage(
+        {
+          customType: CUSTOM_ENTRY_TYPE,
+          content: budgetLimitPrompt(result.goal),
+          display: false,
+          details: { kind: "budget_limit", goalId: result.goal.goalId },
+        },
+        { triggerTurn: true, deliverAs: "steer" },
+      );
+    }
+  };
+
+  return {
+    clearActiveAccounting,
+    beginAccounting,
+    accountProgress,
+  };
+}

package/src/goal-persistence.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { RUNTIME_PERSIST_INTERVAL_MS } from "./runtime-config.js";
+import { clearEntry, cloneGoal, goalsEquivalent, setEntry } from "./state.js";
+import { CUSTOM_ENTRY_TYPE, type GoalEntrySource, type ThreadGoal } from "./types.js";
+
+interface GoalPersistenceDeps {
+  pi: Pick<ExtensionAPI, "appendEntry">;
+}
+
+export function createGoalPersistence(deps: GoalPersistenceDeps) {
+  let goal: ThreadGoal | null = null;
+  let lastPersistedGoal: ThreadGoal | null = null;
+  let lastRuntimePersistAt: number | null = null;
+
+  const getGoal = (): ThreadGoal | null => goal;
+
+  const setGoalSnapshot = (nextGoal: ThreadGoal | null): void => {
+    goal = nextGoal;
+  };
+
+  const syncPersistedSnapshot = (snapshot: ThreadGoal | null): void => {
+    lastPersistedGoal = snapshot ? cloneGoal(snapshot) : null;
+    lastRuntimePersistAt = null;
+  };
+
+  const flushGoalPersistence = (source: GoalEntrySource): boolean => {
+    if (!goal) {
+      return false;
+    }
+    if (lastPersistedGoal && goalsEquivalent(goal, lastPersistedGoal)) {
+      return false;
+    }
+
+    deps.pi.appendEntry(CUSTOM_ENTRY_TYPE, setEntry(goal, source));
+    lastPersistedGoal = cloneGoal(goal);
+    lastRuntimePersistAt = Date.now();
+    return true;
+  };
+
+  const maybeFlushRuntimePersistence = (source: GoalEntrySource): void => {
+    if (!goal || goal.status !== "active") {
+      return;
+    }
+    const now = Date.now();
+    if (lastRuntimePersistAt !== null && now - lastRuntimePersistAt < RUNTIME_PERSIST_INTERVAL_MS) {
+      return;
+    }
+    flushGoalPersistence(source);
+  };
+
+  const clearGoalSnapshot = (): void => {
+    goal = null;
+    lastPersistedGoal = null;
+    lastRuntimePersistAt = null;
+  };
+
+  const appendClearEntry = (clearedGoalId: string | null, source: GoalEntrySource): void => {
+    clearGoalSnapshot();
+    deps.pi.appendEntry(CUSTOM_ENTRY_TYPE, clearEntry(clearedGoalId, source));
+  };
+
+  return {
+    appendClearEntry,
+    flushGoalPersistence,
+    getGoal,
+    maybeFlushRuntimePersistence,
+    setGoalSnapshot,
+    syncPersistedSnapshot,
+  };
+}
+
+export type GoalPersistence = ReturnType<typeof createGoalPersistence>;

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

@@ -0,0 +1,51 @@
+import type { AgentEndEvent, ExtensionHandler } from "@earendil-works/pi-coding-agent";
+
+import { assistantTurnTokens, isAbortedAssistantMessage } from "./goal-accounting.js";
+import { isErrorAssistantMessage, type AssistantErrorMessage } from "./recovery.js";
+import {
+  handleAgentErrorMessage,
+  recordAssistantContextOverflow,
+  runStaleQueuedWorkPlan,
+} from "./goal-runtime-event-utils.js";
+import type { GoalRuntimeAgentHandlerContext } from "./goal-runtime-event-handler-types.js";
+
+export function createAgentEventHandlers(deps: GoalRuntimeAgentHandlerContext) {
+  const { runtimeState, stateController, continuation, goalAccounting, resetErrorRecovery } = deps;
+
+  return {
+    onAgentEnd: (async (event, ctx) => {
+      continuation.clearPassthroughContinuationInput();
+      if (runStaleQueuedWorkPlan(runtimeState.staleQueuedWorkGuard.planAgentEnd(event.messages), ctx, deps)) {
+        return;
+      }
+
+      const abortedMessages = event.messages.filter(isAbortedAssistantMessage);
+      const abortedTurnTokens = abortedMessages.reduce((sum, message) => {
+        return sum + assistantTurnTokens(message);
+      }, 0);
+      goalAccounting.accountProgress(ctx, false, abortedTurnTokens, true);
+      stateController.flushGoalPersistence("runtime");
+      if (abortedMessages.length > 0) {
+        stateController.pauseForAbort(ctx);
+        return;
+      }
+      const errorMessages = event.messages.filter(isErrorAssistantMessage);
+      if (errorMessages.length > 0) {
+        const lastError = errorMessages.at(-1) as AssistantErrorMessage | undefined;
+        if (lastError) {
+          handleAgentErrorMessage(lastError, ctx, deps);
+        }
+        return;
+      }
+
+      const lastAssistant = [...event.messages]
+        .reverse()
+        .find((message) => message.role === "assistant");
+      if (lastAssistant && recordAssistantContextOverflow(lastAssistant, ctx, deps)) {
+        return;
+      }
+      resetErrorRecovery();
+      continuation.requestContinuation(ctx);
+    }) satisfies ExtensionHandler<AgentEndEvent>,
+  };
+}

package/src/goal-runtime-controller.ts

@@ -0,0 +1,162 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { registerGoalCommand } from "./commands.js";
+import { createContinuationScheduler } from "./continuation-scheduler.js";
+import { createGoalAccounting } from "./goal-accounting.js";
+import { createGoalPersistence } from "./goal-persistence.js";
+import {
+  createGoalRuntimeEventHandlers,
+  type GoalRuntimeEventHandlers,
+} from "./goal-runtime-event-handlers.js";
+import { registerGoalRuntimeEvents } from "./goal-runtime-events.js";
+import { createGoalRuntimeState } from "./goal-runtime-state.js";
+import { createGoalRuntimeStatus } from "./goal-runtime-status.js";
+import { createGoalStateController } from "./goal-state-controller.js";
+import { createGoalRecoveryRuntime } from "./recovery-runtime.js";
+import {
+  clearActiveHostOverflowRecovery,
+  resetRecoveryMachine,
+  setRecoveryPausedAttention,
+} from "./recovery-machine.js";
+import { goalWithLiveUsage } from "./state.js";
+import { registerGoalTools } from "./tools.js";
+import type { GoalEntrySource, GoalResult, ThreadGoal } from "./types.js";
+
+export interface GoalRuntimeController extends GoalRuntimeEventHandlers {
+  getGoalForDisplay(): ThreadGoal | null;
+  setGoal(goal: ThreadGoal, source: GoalEntrySource, ctx: ExtensionContext): void;
+  clearGoal(source: GoalEntrySource, ctx: ExtensionContext): void;
+  updateGoal(status: "complete" | "blocked", source: GoalEntrySource, ctx: ExtensionContext): GoalResult;
+  requestContinuation(ctx: ExtensionContext): void;
+}
+
+export function createGoalRuntimeController(pi: ExtensionAPI): GoalRuntimeController {
+  const runtimeState = createGoalRuntimeState();
+  const persistence = createGoalPersistence({ pi });
+
+  const clearActiveAccounting = (): void => {
+    runtimeState.accounting.activeGoalId = null;
+    runtimeState.accounting.lastAccountedAt = null;
+  };
+
+  const resetErrorRecovery = (): void => {
+    resetRecoveryMachine(runtimeState.recoveryState);
+  };
+
+  const goalForDisplay = () =>
+    goalWithLiveUsage(
+      persistence.getGoal(),
+      runtimeState.accounting.activeGoalId,
+      runtimeState.accounting.lastAccountedAt,
+    );
+
+  const status = createGoalRuntimeStatus({
+    getGoalForDisplay: goalForDisplay,
+    getGoalStatus: () => persistence.getGoal()?.status ?? null,
+    getRecoveryAttention: () => runtimeState.recoveryState.attention,
+  });
+
+  const continuation = createContinuationScheduler({
+    pi,
+    getGoal: () => persistence.getGoal(),
+    getRecoveryState: () => runtimeState.recoveryState,
+    staleQueuedWorkGuard: runtimeState.staleQueuedWorkGuard,
+    getCurrentTurnIndex: () => runtimeState.currentTurnIndex,
+  });
+
+  const stateController = createGoalStateController({
+    pi,
+    persistence,
+    getRecoveryState: () => runtimeState.recoveryState,
+    transitionEffectHandlers: {
+      clearContinuation: continuation.clearContinuationState,
+      clearActiveAccounting,
+      resetRecovery: resetErrorRecovery,
+      clearBudgetWarning: () => {
+        runtimeState.accounting.budgetWarningSentFor = null;
+      },
+      clearHostOverflowRecovery: () => {
+        clearActiveHostOverflowRecovery(runtimeState.recoveryState);
+      },
+      setRecoveryPausedAttention: (reason: string) => {
+        setRecoveryPausedAttention(runtimeState.recoveryState, reason);
+      },
+      markContinuationQueued: continuation.markContinuationQueued,
+      stopStatusRefresh: () => status.stopStatusRefresh(),
+    },
+    refreshUi: (ctx) => status.refreshUi(ctx),
+  });
+
+  const goalAccounting = createGoalAccounting({
+    getGoal: () => stateController.getGoal(),
+    getAccounting: () => runtimeState.accounting,
+    applyRuntimeAccountingTransition(ctx, nextGoal) {
+      stateController.applyGoalTransition({ kind: "runtime_accounting", nextGoal }, ctx);
+    },
+    sendMessage: pi.sendMessage.bind(pi),
+  });
+
+  const recoveryRuntime = createGoalRecoveryRuntime({
+    getGoal: () => stateController.getGoal(),
+    getRecoveryState: () => runtimeState.recoveryState,
+    clearContinuationState: continuation.clearContinuationState,
+    pauseGoalForRecovery(ctx, recoveryReason) {
+      stateController.applyGoalTransition(
+        { kind: "recovery_pause", recoveryReason },
+        ctx,
+      );
+    },
+    refreshUi: status.refreshUi,
+    requestContinuation: continuation.requestContinuation,
+  });
+
+  const eventHandlers = createGoalRuntimeEventHandlers({
+    pi,
+    runtimeState,
+    stateController,
+    continuation,
+    goalAccounting,
+    recoveryRuntime,
+    status,
+    clearActiveAccounting,
+    resetErrorRecovery,
+  });
+
+  const updateGoal = (
+    status: "complete" | "blocked",
+    source: GoalEntrySource,
+    ctx: ExtensionContext,
+  ): GoalResult => {
+    goalAccounting.accountProgress(ctx, false, 0, true);
+    return stateController.updateGoal(status, source, ctx);
+  };
+
+  return {
+    getGoalForDisplay: goalForDisplay,
+    setGoal(nextGoal, source, ctx) {
+      stateController.applyGoalTransition({ kind: "set", nextGoal, source }, ctx);
+    },
+    clearGoal(source, ctx) {
+      stateController.applyGoalTransition({ kind: "clear", source }, ctx);
+    },
+    updateGoal,
+    requestContinuation: continuation.requestContinuation,
+    ...eventHandlers,
+  };
+}
+
+export function registerGoalRuntimeController(pi: ExtensionAPI): void {
+  const controller = createGoalRuntimeController(pi);
+  registerGoalTools(pi, {
+    getGoal: () => controller.getGoalForDisplay(),
+    setGoal: controller.setGoal.bind(controller),
+    updateGoal: controller.updateGoal.bind(controller),
+  });
+  registerGoalCommand(pi, {
+    getGoal: () => controller.getGoalForDisplay(),
+    setGoal: controller.setGoal.bind(controller),
+    clearGoal: controller.clearGoal.bind(controller),
+    requestContinuation: controller.requestContinuation.bind(controller),
+  });
+  registerGoalRuntimeEvents(pi, controller);
+}