Merge pull request #39 from asynkron/codex/ensure-.openagent-folder-and-manage-plans

Persist merged plan snapshot for agent runtime

Author: rogeralsing

.openagent/todo.md

@@ -0,0 +1,3 @@
+# Active Plan
+
+_No active plan._

src/agent/context.md

@@ -25,6 +25,7 @@
   2. `approvalManager.js` determines whether a proposed command can run automatically or needs a human decision.
   3. `commandExecution.js` executes built-ins before shell commands and returns structured execution metadata.
 - After every pass, `observationBuilder.js` converts command output into both CLI previews and history observations so the next model call has the right context.
+- `loop.js` maintains an active plan manager that merges partial LLM plan updates, emits the merged outline to UIs, and writes a snapshot to `.openagent/todo.md` at repo root so humans can inspect the current plan.
 - Integration suites mock `openaiRequest.js` to enqueue deterministic completions, reflecting the module boundaries introduced by this architecture.
 
 ## Positive Signals

src/agent/loop.js

@@ -3,6 +3,9 @@
  * writing directly to the CLI.
  */
 
+import { mkdir, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
 import { SYSTEM_PROMPT } from '../config/systemPrompt.js';
 import { getOpenAIClient, MODEL } from '../openai/client.js';
 import {
@@ -29,6 +32,7 @@ import { createEscState } from './escState.js';
 import { AsyncQueue, QUEUE_DONE } from '../utils/asyncQueue.js';
 import { cancel as cancelActive } from '../utils/cancellation.js';
 import { PromptCoordinator } from './promptCoordinator.js';
+import { mergePlanTrees, planToMarkdown } from '../utils/plan.js';
 
 const NO_HUMAN_AUTO_MESSAGE = "continue or say 'done'";
 const PLAN_PENDING_REMINDER =
@@ -60,6 +64,47 @@ export function createAgentRuntime({
   const outputs = new AsyncQueue();
   const inputs = new AsyncQueue();
 
+  const planDirectoryPath = resolve(process.cwd(), '.openagent');
+  const planFilePath = resolve(planDirectoryPath, 'todo.md');
+  let activePlan = [];
+
+  const persistPlanSnapshot = async () => {
+    try {
+      await mkdir(planDirectoryPath, { recursive: true });
+      const snapshot = planToMarkdown(activePlan);
+      await writeFile(planFilePath, snapshot, 'utf8');
+    } catch (error) {
+      outputs.push({
+        type: 'status',
+        level: 'warn',
+        message: 'Failed to persist plan snapshot to .openagent/todo.md.',
+        details: error instanceof Error ? error.message : String(error),
+      });
+    }
+  };
+
+  const planManager = {
+    get() {
+      return mergePlanTrees([], activePlan);
+    },
+    async update(nextPlan) {
+      if (!Array.isArray(nextPlan) || nextPlan.length === 0) {
+        activePlan = [];
+      } else if (activePlan.length === 0) {
+        activePlan = mergePlanTrees([], nextPlan);
+      } else {
+        activePlan = mergePlanTrees(activePlan, nextPlan);
+      }
+
+      await persistPlanSnapshot();
+      return mergePlanTrees([], activePlan);
+    },
+    async initialize() {
+      await persistPlanSnapshot();
+      return mergePlanTrees([], activePlan);
+    },
+  };
+
   const { state: escState, trigger: triggerEsc, detach: detachEscListener } = createEscState();
   const promptCoordinator = new PromptCoordinator({
     emitEvent: (event) => outputs.push(event),
@@ -142,6 +187,8 @@ export function createAgentRuntime({
     running = true;
     inputProcessorPromise = processInputEvents();
 
+    await planManager.initialize();
+
     emit({ type: 'banner', title: 'OpenAgent - AI Agent with JSON Protocol' });
     emit({ type: 'status', level: 'info', message: 'Submit prompts to drive the conversation.' });
     if (getAutoApproveFlag()) {
@@ -214,6 +261,7 @@ export function createAgentRuntime({
               escState,
               approvalManager,
               historyCompactor,
+              planManager,
             });
 
             continueLoop = shouldContinue;

src/agent/passExecutor.js

@@ -29,6 +29,7 @@ export async function executeAgentPass({
   escState,
   approvalManager,
   historyCompactor,
+  planManager,
 }) {
   const observationBuilder = new ObservationBuilder({
     combineStdStreams,
@@ -123,7 +124,38 @@ export async function executeAgentPass({
   }
 
   emitEvent({ type: 'assistant-message', message: parsed.message ?? '' });
-  emitEvent({ type: 'plan', plan: Array.isArray(parsed.plan) ? parsed.plan : [] });
+
+  const incomingPlan = Array.isArray(parsed.plan) ? parsed.plan : null;
+  let activePlan = incomingPlan ?? [];
+
+  if (planManager) {
+    try {
+      if (incomingPlan && typeof planManager.update === 'function') {
+        const merged = await planManager.update(incomingPlan);
+        if (Array.isArray(merged)) {
+          activePlan = merged;
+        }
+      } else if (!incomingPlan && typeof planManager.get === 'function') {
+        const snapshot = planManager.get();
+        if (Array.isArray(snapshot)) {
+          activePlan = snapshot;
+        }
+      }
+    } catch (error) {
+      emitEvent({
+        type: 'status',
+        level: 'warn',
+        message: 'Failed to update persistent plan state.',
+        details: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  if (!Array.isArray(activePlan)) {
+    activePlan = incomingPlan ?? [];
+  }
+
+  emitEvent({ type: 'plan', plan: activePlan });
 
   if (!parsed.command) {
     if (
@@ -139,7 +171,7 @@ export async function executeAgentPass({
       }
     }
 
-    if (Array.isArray(parsed.plan) && planHasOpenSteps(parsed.plan)) {
+    if (Array.isArray(activePlan) && planHasOpenSteps(activePlan)) {
       emitEvent({
         type: 'status',
         level: 'warn',

src/utils/context.md

@@ -9,7 +9,7 @@
 - `asyncQueue.js`: exposes the `AsyncQueue` class (with a compatibility factory) used to shuttle events between the agent loop and UIs.
 - `cancellation.js`: stack-based cancellation manager enabling ESC-triggered aborts and nested operations.
 - `output.js`: merges stdout/stderr and provides preview builders used when rendering command results.
-- `plan.js`: supplies plan inspection helpers (e.g., `planHasOpenSteps`).
+- `plan.js`: supplies plan inspection helpers (e.g., `planHasOpenSteps`) plus merge/serialization utilities that keep the active plan snapshot in sync with `.openagent/todo.md`.
 - `text.js`: regex filtering, tailing, truncation, and lightweight shell argument splitting.
 - `contextUsage.js`: estimates token usage/remaining context for the current conversation history.
 - `jsonAssetValidator.js`: shared helpers for JSON schema validation and prompt copy synchronization checks.

src/utils/plan.js

@@ -2,6 +2,139 @@
  * Plan utilities extracted from the agent loop.
  */
 
+const PLAN_CHILD_KEYS = ['substeps', 'children', 'steps'];
+
+function normalizeStepLabel(stepValue) {
+  if (stepValue === null || stepValue === undefined) {
+    return '';
+  }
+
+  const raw = String(stepValue).trim();
+  if (!raw) {
+    return '';
+  }
+
+  return raw.replace(/\.+$/, '');
+}
+
+function createPlanKey(item, fallbackIndex) {
+  if (!item || typeof item !== 'object') {
+    return `index:${fallbackIndex}`;
+  }
+
+  const label = normalizeStepLabel(item.step);
+  if (label) {
+    return `step:${label.toLowerCase()}`;
+  }
+
+  if (typeof item.title === 'string' && item.title.trim().length > 0) {
+    return `title:${item.title.trim().toLowerCase()}`;
+  }
+
+  return `index:${fallbackIndex}`;
+}
+
+function clonePlanItem(item) {
+  if (!item || typeof item !== 'object') {
+    return {};
+  }
+
+  const cloned = { ...item };
+
+  for (const key of PLAN_CHILD_KEYS) {
+    if (Array.isArray(item[key])) {
+      cloned[key] = item[key].map((child) => clonePlanItem(child));
+    } else if (cloned[key] && !Array.isArray(cloned[key])) {
+      delete cloned[key];
+    }
+  }
+
+  return cloned;
+}
+
+function selectChildKey(existingItem, incomingItem) {
+  for (const key of PLAN_CHILD_KEYS) {
+    if (Array.isArray(incomingItem?.[key])) {
+      return key;
+    }
+  }
+
+  for (const key of PLAN_CHILD_KEYS) {
+    if (Array.isArray(existingItem?.[key])) {
+      return key;
+    }
+  }
+
+  return null;
+}
+
+function mergePlanItems(existingItem, incomingItem) {
+  if (!incomingItem || typeof incomingItem !== 'object') {
+    return clonePlanItem(existingItem);
+  }
+
+  if (!existingItem || typeof existingItem !== 'object') {
+    return clonePlanItem(incomingItem);
+  }
+
+  const base = clonePlanItem(existingItem);
+  const incoming = clonePlanItem(incomingItem);
+  const merged = { ...base, ...incoming };
+
+  const childKey = selectChildKey(existingItem, incomingItem);
+  if (childKey) {
+    const existingChildren = Array.isArray(existingItem[childKey]) ? existingItem[childKey] : [];
+    const incomingChildren = Array.isArray(incomingItem[childKey]) ? incomingItem[childKey] : [];
+    merged[childKey] = mergePlanTrees(existingChildren, incomingChildren);
+
+    for (const key of PLAN_CHILD_KEYS) {
+      if (key !== childKey && key in merged) {
+        delete merged[key];
+      }
+    }
+  }
+
+  return merged;
+}
+
+export function mergePlanTrees(existingPlan = [], incomingPlan = []) {
+  const existing = Array.isArray(existingPlan) ? existingPlan : [];
+  const incoming = Array.isArray(incomingPlan) ? incomingPlan : [];
+
+  if (incoming.length === 0) {
+    return [];
+  }
+
+  const existingIndex = new Map();
+  existing.forEach((item, index) => {
+    existingIndex.set(createPlanKey(item, index), { item, index });
+  });
+
+  const usedKeys = new Set();
+  const result = [];
+
+  incoming.forEach((item, index) => {
+    const key = createPlanKey(item, index);
+    const existingMatch = existingIndex.get(key);
+
+    if (existingMatch) {
+      result.push(mergePlanItems(existingMatch.item, item));
+      usedKeys.add(key);
+    } else {
+      result.push(clonePlanItem(item));
+    }
+  });
+
+  existing.forEach((item, index) => {
+    const key = createPlanKey(item, index);
+    if (!usedKeys.has(key)) {
+      result.push(clonePlanItem(item));
+    }
+  });
+
+  return result;
+}
+
 export function planHasOpenSteps(plan) {
   const hasOpen = (items) => {
     if (!Array.isArray(items)) {
@@ -16,7 +149,8 @@ export function planHasOpenSteps(plan) {
       const normalizedStatus =
         typeof item.status === 'string' ? item.status.trim().toLowerCase() : '';
 
-      if (Array.isArray(item.substeps) && hasOpen(item.substeps)) {
+      const childKey = PLAN_CHILD_KEYS.find((key) => Array.isArray(item[key]));
+      if (childKey && hasOpen(item[childKey])) {
         return true;
       }
 
@@ -31,6 +165,75 @@ export function planHasOpenSteps(plan) {
   return hasOpen(plan);
 }
 
+function formatPlanLine(item, index, ancestors, depth, lines) {
+  if (!item || typeof item !== 'object') {
+    return;
+  }
+
+  const sanitizedStep = normalizeStepLabel(item.step);
+  const hasExplicitStep = sanitizedStep.length > 0;
+  const labelParts = hasExplicitStep
+    ? sanitizedStep.split('.').filter((part) => part.length > 0)
+    : [...ancestors, String(index + 1)];
+
+  const stepLabel = labelParts.join('.');
+  const indent = '  '.repeat(depth);
+  const title = typeof item.title === 'string' && item.title.trim().length > 0 ? item.title.trim() : '';
+  const status = typeof item.status === 'string' && item.status.trim().length > 0 ? item.status.trim() : '';
+
+  const lineParts = [];
+  if (stepLabel) {
+    lineParts.push(`Step ${stepLabel}`);
+  }
+  if (title) {
+    lineParts.push(`- ${title}`);
+  }
+  if (status) {
+    lineParts.push(`[${status}]`);
+  }
+
+  if (lineParts.length === 0) {
+    return;
+  }
+
+  lines.push(`${indent}${lineParts.join(' ')}`.trimEnd());
+
+  const childKey = PLAN_CHILD_KEYS.find((key) => Array.isArray(item[key]));
+  if (childKey) {
+    const nextAncestors = hasExplicitStep ? labelParts : [...ancestors, String(index + 1)];
+    formatPlanSection(item[childKey], nextAncestors, depth + 1, lines);
+  }
+}
+
+function formatPlanSection(items, ancestors, depth, lines) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return;
+  }
+
+  items.forEach((item, index) => {
+    formatPlanLine(item, index, ancestors, depth, lines);
+  });
+}
+
+export function planToMarkdown(plan) {
+  const header = '# Active Plan\n\n';
+
+  if (!Array.isArray(plan) || plan.length === 0) {
+    return `${header}_No active plan._\n`;
+  }
+
+  const lines = [];
+  formatPlanSection(plan, [], 0, lines);
+
+  if (lines.length === 0) {
+    return `${header}_No active plan._\n`;
+  }
+
+  return `${header}${lines.join('\n')}\n`;
+}
+
 export default {
+  mergePlanTrees,
   planHasOpenSteps,
+  planToMarkdown,
 };