@golba98/codexa 1.0.1

package/src/session/liveRenderScheduler.test.ts

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createLiveRenderScheduler, type LiveRenderUpdate } from "./liveRenderScheduler.js";
+
+type FakeTimer = {
+  callback: () => void;
+  delayMs: number;
+  cleared: boolean;
+};
+
+function createFakeTimers() {
+  const timers: FakeTimer[] = [];
+  return {
+    timers,
+    setTimer(callback: () => void, delayMs: number) {
+      const timer: FakeTimer = { callback, delayMs, cleared: false };
+      timers.push(timer);
+      return timer as unknown as ReturnType<typeof setTimeout>;
+    },
+    clearTimer(timer: ReturnType<typeof setTimeout>) {
+      (timer as unknown as FakeTimer).cleared = true;
+    },
+  };
+}
+
+function progress(id: string, text: string): LiveRenderUpdate {
+  return { type: "progress", update: { id, source: "reasoning", text } };
+}
+
+function tool(id: string, status: "running" | "completed"): LiveRenderUpdate {
+  return {
+    type: "tool",
+    activity: {
+      id,
+      command: "Get-Content README.md",
+      status,
+      startedAt: 1,
+      completedAt: status === "completed" ? 2 : undefined,
+    },
+  };
+}
+
+test("coalesces adjacent assistant chunks at the cadence flush", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const fakeTimers = createFakeTimers();
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 50,
+    flush: (updates) => flushed.push(updates),
+    setTimer: fakeTimers.setTimer,
+    clearTimer: fakeTimers.clearTimer,
+  });
+
+  scheduler.enqueue({ type: "assistant", chunk: "Hello" });
+  scheduler.enqueue({ type: "assistant", chunk: ", world" });
+
+  assert.equal(flushed.length, 0);
+  assert.equal(fakeTimers.timers.length, 1);
+  assert.equal(fakeTimers.timers[0]?.delayMs, 50);
+  fakeTimers.timers[0]!.callback();
+
+  assert.equal(flushed.length, 1);
+  assert.deepEqual(flushed[0], [{ type: "assistant", chunk: "Hello, world" }]);
+});
+
+test("first progress-only update waits for the progress cadence", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const fakeTimers = createFakeTimers();
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 50,
+    flush: (updates) => flushed.push(updates),
+    setTimer: fakeTimers.setTimer,
+    clearTimer: fakeTimers.clearTimer,
+  });
+
+  scheduler.enqueue(tool("t1", "running"));
+
+  assert.equal(flushed.length, 0);
+  assert.equal(fakeTimers.timers.length, 1);
+  assert.equal(fakeTimers.timers[0]?.delayMs, 50);
+
+  fakeTimers.timers[0]!.callback();
+  assert.deepEqual(flushed[0]?.map((update) => update.type), ["tool"]);
+});
+
+test("preserves event order while keeping only the latest same-id progress update", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 50,
+    flush: (updates) => flushed.push(updates),
+  });
+
+  scheduler.enqueue(progress("p1", "Thinking"));
+  scheduler.enqueue(tool("t1", "running"));
+  scheduler.enqueue({ type: "assistant", chunk: "First" });
+  scheduler.enqueue({ type: "assistant", chunk: " segment" });
+  scheduler.enqueue(progress("p1", "Thinking harder"));
+  scheduler.flushNow();
+
+  assert.deepEqual(flushed[0]?.map((update) => update.type), ["progress", "tool", "assistant"]);
+  assert.equal((flushed[0]?.[2] as Extract<LiveRenderUpdate, { type: "assistant" }>).chunk, "First segment");
+  assert.equal((flushed[0]?.[0] as Extract<LiveRenderUpdate, { type: "progress" }>).update.text, "Thinking harder");
+});
+
+test("coalesces repeated keyed progress and tool updates across a noisy flush window", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 175,
+    flush: (updates) => flushed.push(updates),
+  });
+
+  scheduler.enqueue(progress("p1", "Reading file 1"));
+  scheduler.enqueue(tool("t1", "running"));
+  scheduler.enqueue(progress("p1", "Reading file 2"));
+  scheduler.enqueue(tool("t1", "completed"));
+  scheduler.enqueue(progress("p2", "Listing files"));
+  scheduler.flushNow();
+
+  assert.deepEqual(flushed[0]?.map((update) => update.type), ["progress", "tool", "progress"]);
+  assert.equal((flushed[0]?.[0] as Extract<LiveRenderUpdate, { type: "progress" }>).update.text, "Reading file 2");
+  assert.equal((flushed[0]?.[1] as Extract<LiveRenderUpdate, { type: "tool" }>).activity.status, "completed");
+});
+
+test("records scheduler flush diagnostics", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const fakeTimers = createFakeTimers();
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 175,
+    flush: (updates) => flushed.push(updates),
+    setTimer: fakeTimers.setTimer,
+    clearTimer: fakeTimers.clearTimer,
+  });
+
+  scheduler.enqueue(progress("p1", "Listing files"));
+  assert.equal(scheduler.getStats().providerEvents, 1);
+  assert.equal(fakeTimers.timers[0]?.delayMs, 175);
+  fakeTimers.timers[0]!.callback();
+
+  scheduler.enqueue({ type: "assistant", chunk: "hello" });
+  assert.equal(fakeTimers.timers[1]?.delayMs, 50);
+  fakeTimers.timers[1]!.callback();
+
+  const stats = scheduler.getStats();
+  assert.equal(stats.providerEvents, 2);
+  assert.equal(stats.flushes, 2);
+  assert.ok(stats.maxFlushIntervalMs >= 0);
+  assert.ok(stats.averageFlushIntervalMs >= 0);
+});
+
+test("prevents reentrant flushes when a producer enqueues during a flush", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  let inFlush = false;
+  let scheduler: ReturnType<typeof createLiveRenderScheduler>;
+
+  scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 50,
+    flush: (updates) => {
+      assert.equal(inFlush, false, "flush should not reenter itself");
+      inFlush = true;
+      flushed.push(updates);
+      if (flushed.length === 1) {
+        scheduler.enqueue({ type: "assistant", chunk: "queued during flush" });
+      }
+      inFlush = false;
+    },
+  });
+
+  scheduler.enqueue({ type: "assistant", chunk: "first" });
+
+  assert.equal(scheduler.flushNow(), true);
+  assert.equal(flushed.length, 2);
+  assert.equal((flushed[0]?.[0] as Extract<LiveRenderUpdate, { type: "assistant" }>).chunk, "first");
+  assert.equal((flushed[1]?.[0] as Extract<LiveRenderUpdate, { type: "assistant" }>).chunk, "queued during flush");
+});
+
+test("flushNow drains queued updates before finalization", () => {
+  const flushed: LiveRenderUpdate[][] = [];
+  const fakeTimers = createFakeTimers();
+  const scheduler = createLiveRenderScheduler({
+    assistantFlushMs: 50,
+    progressOnlyFlushMs: 50,
+    flush: (updates) => flushed.push(updates),
+    setTimer: fakeTimers.setTimer,
+    clearTimer: fakeTimers.clearTimer,
+  });
+
+  scheduler.enqueue({ type: "assistant", chunk: "final chunk" });
+
+  assert.equal(scheduler.flushNow(), true);
+  assert.equal(flushed.length, 1);
+  assert.equal(scheduler.hasPendingUpdates(), false);
+
+  assert.equal(fakeTimers.timers[0]?.cleared, true);
+  fakeTimers.timers[0]?.callback();
+  assert.equal(flushed.length, 1);
+});

package/src/session/liveRenderScheduler.ts

@@ -0,0 +1,214 @@
+import type { BackendProgressUpdate } from "../core/providers/types.js";
+import type { RunFileActivity } from "../core/workspaceActivity.js";
+import type { RunToolActivity } from "./types.js";
+import * as renderDebug from "../core/perf/renderDebug.js";
+
+export type LiveRenderUpdate =
+  | { type: "assistant"; chunk: string }
+  | { type: "plan"; chunk: string }
+  | { type: "progress"; update: BackendProgressUpdate }
+  | { type: "activity"; activity: RunFileActivity[] }
+  | { type: "tool"; activity: RunToolActivity };
+
+type TimerHandle = ReturnType<typeof setTimeout>;
+
+export interface LiveRenderSchedulerOptions {
+  flush: (updates: LiveRenderUpdate[]) => void;
+  assistantFlushMs: number;
+  progressOnlyFlushMs: number;
+  setTimer?: (callback: () => void, delayMs: number) => TimerHandle;
+  clearTimer?: (timer: TimerHandle) => void;
+}
+
+export interface LiveRenderScheduler {
+  enqueue: (update: LiveRenderUpdate) => void;
+  flushNow: () => boolean;
+  cancel: () => void;
+  hasPendingUpdates: () => boolean;
+  getStats: () => LiveRenderSchedulerStats;
+}
+
+export interface LiveRenderSchedulerStats {
+  providerEvents: number;
+  flushes: number;
+  averageFlushIntervalMs: number;
+  maxFlushIntervalMs: number;
+}
+
+// ─── Update coalescing ───────────────────────────────────────────────────────
+
+function findPendingUpdateIndex(
+  updates: LiveRenderUpdate[],
+  predicate: (update: LiveRenderUpdate) => boolean,
+): number {
+  for (let index = updates.length - 1; index >= 0; index -= 1) {
+    if (predicate(updates[index]!)) return index;
+  }
+  return -1;
+}
+
+function mergeLiveRenderUpdate(updates: LiveRenderUpdate[], update: LiveRenderUpdate): boolean {
+  const previous = updates[updates.length - 1];
+
+  if (update.type === "assistant" || update.type === "plan") {
+    if (previous?.type === update.type) {
+      previous.chunk += update.chunk;
+    } else {
+      updates.push({ ...update });
+    }
+    return true;
+  }
+
+  if (update.type === "progress") {
+    const index = findPendingUpdateIndex(
+      updates,
+      (pending) => pending.type === "progress" && pending.update.id === update.update.id,
+    );
+    if (index >= 0 && updates[index]?.type === "progress") {
+      updates[index] = update;
+    } else {
+      updates.push(update);
+    }
+    return false;
+  }
+
+  if (update.type === "tool") {
+    const index = findPendingUpdateIndex(
+      updates,
+      (pending) => pending.type === "tool" && pending.activity.id === update.activity.id,
+    );
+    if (index >= 0 && updates[index]?.type === "tool") {
+      const previousTool = updates[index];
+      updates[index] = {
+        type: "tool",
+        activity: { ...previousTool.activity, ...update.activity },
+      };
+    } else {
+      updates.push(update);
+    }
+    return false;
+  }
+
+  const activityIndex = findPendingUpdateIndex(updates, (pending) => pending.type === "activity");
+  if (activityIndex >= 0 && updates[activityIndex]?.type === "activity") {
+    updates[activityIndex].activity.push(...update.activity);
+  } else {
+    updates.push({ type: "activity", activity: [...update.activity] });
+  }
+  return false;
+}
+
+// ─── Scheduler ───────────────────────────────────────────────────────────────
+
+export function createLiveRenderScheduler({
+  flush,
+  assistantFlushMs,
+  progressOnlyFlushMs,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+}: LiveRenderSchedulerOptions): LiveRenderScheduler {
+  let pendingUpdates: LiveRenderUpdate[] = [];
+  let hasPendingAssistantDelta = false;
+  let timer: TimerHandle | null = null;
+  let isFlushing = false;
+  let flushAgain = false;
+  let providerEvents = 0;
+  let flushes = 0;
+  let totalFlushIntervalMs = 0;
+  let maxFlushIntervalMs = 0;
+  let lastFlushMonotonicMs: number | null = null;
+
+  const cancelScheduledFlush = () => {
+    if (timer) {
+      clearTimer(timer);
+      timer = null;
+    }
+  };
+
+  const drain = (): boolean => {
+    if (isFlushing) {
+      flushAgain = true;
+      return false;
+    }
+
+    cancelScheduledFlush();
+
+    if (pendingUpdates.length === 0) {
+      hasPendingAssistantDelta = false;
+      return false;
+    }
+
+    isFlushing = true;
+    let flushed = false;
+    try {
+      do {
+        flushAgain = false;
+        const updates = pendingUpdates;
+        pendingUpdates = [];
+        hasPendingAssistantDelta = false;
+        if (updates.length > 0) {
+          flushed = true;
+          const startedAt = performance.now();
+          flush(updates);
+          flushes += 1;
+          if (lastFlushMonotonicMs !== null) {
+            const intervalMs = Math.max(0, Math.round(startedAt - lastFlushMonotonicMs));
+            totalFlushIntervalMs += intervalMs;
+            maxFlushIntervalMs = Math.max(maxFlushIntervalMs, intervalMs);
+          }
+          lastFlushMonotonicMs = startedAt;
+          renderDebug.traceSchedulerFlush({
+            reason: updates.some((update) => update.type === "assistant" || update.type === "plan") ? "stream" : "progress",
+            updates: updates.length,
+            assistantChunks: updates.filter((update) => update.type === "assistant").length,
+            progressUpdates: updates.filter((update) => update.type === "progress").length,
+            toolUpdates: updates.filter((update) => update.type === "tool").length,
+            activityUpdates: updates.filter((update) => update.type === "activity").length,
+            durationMs: Math.round(performance.now() - startedAt),
+          });
+        }
+      } while (flushAgain || pendingUpdates.length > 0);
+    } finally {
+      isFlushing = false;
+    }
+
+    return flushed;
+  };
+
+  const schedule = () => {
+    if (timer || isFlushing) return;
+
+    const interval = hasPendingAssistantDelta ? assistantFlushMs : progressOnlyFlushMs;
+    timer = setTimer(() => {
+      timer = null;
+      drain();
+    }, interval);
+  };
+
+  return {
+    enqueue(update) {
+      providerEvents += 1;
+      const addedAssistant = mergeLiveRenderUpdate(pendingUpdates, update);
+      hasPendingAssistantDelta ||= addedAssistant;
+      schedule();
+    },
+    flushNow: drain,
+    cancel() {
+      cancelScheduledFlush();
+      pendingUpdates = [];
+      hasPendingAssistantDelta = false;
+    },
+    hasPendingUpdates() {
+      return pendingUpdates.length > 0;
+    },
+    getStats() {
+      const intervalCount = Math.max(0, flushes - 1);
+      return {
+        providerEvents,
+        flushes,
+        averageFlushIntervalMs: intervalCount > 0 ? Math.round(totalFlushIntervalMs / intervalCount) : 0,
+        maxFlushIntervalMs,
+      };
+    },
+  };
+}

package/src/session/planFlow.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  approvePlanExecution,
+  beginPlanFeedback,
+  cancelPlanFeedback,
+  createInitialPlanFlowState,
+  finishPlanGeneration,
+  resetPlanFlow,
+  startPlanGeneration,
+  submitPlanFeedback,
+} from "./planFlow.js";
+
+test("starts a fresh plan generation flow from idle", () => {
+  const state = startPlanGeneration("Build a hello world script", "auto-edit");
+
+  assert.deepEqual(createInitialPlanFlowState(), { kind: "idle" });
+  assert.equal(state.kind, "generating");
+  assert.equal(state.originalPrompt, "Build a hello world script");
+  assert.equal(state.executionMode, "auto-edit");
+  assert.deepEqual(state.constraints, []);
+  assert.equal(state.planFilePath, null);
+  assert.equal(state.currentPlan, null);
+  assert.equal(state.pendingFeedback, null);
+});
+
+test("finishes plan generation into an awaiting-action state with a plan file path", () => {
+  const state = finishPlanGeneration(
+    startPlanGeneration("Build a hello world script", "auto-edit"),
+    "## Files\n- hello_world.py",
+    "C:\\Workspace\\.codexa\\last-plan.md",
+  );
+
+  assert.equal(state.kind, "awaiting_action");
+  assert.equal(state.currentPlan, "## Files\n- hello_world.py");
+  assert.equal(state.planFilePath, "C:\\Workspace\\.codexa\\last-plan.md");
+});
+
+test("revising the plan keeps constraints and records revision feedback", () => {
+  const awaiting = finishPlanGeneration(
+    startPlanGeneration("Build a hello world script", "auto-edit"),
+    "Plan v1",
+    "C:\\Workspace\\.codexa\\last-plan.md",
+  );
+  const collecting = beginPlanFeedback(awaiting, "revise");
+  const generating = submitPlanFeedback(collecting, "Keep it to a single file.");
+
+  assert.equal(collecting.kind, "collecting_feedback");
+  assert.equal(collecting.mode, "revise");
+  assert.equal(generating.kind, "generating");
+  assert.equal(generating.currentPlan, "Plan v1");
+  assert.equal(generating.planFilePath, "C:\\Workspace\\.codexa\\last-plan.md");
+  assert.deepEqual(generating.constraints, []);
+  assert.deepEqual(generating.pendingFeedback, {
+    mode: "revise",
+    text: "Keep it to a single file.",
+  });
+});
+
+test("adding constraints accumulates them before the next plan pass", () => {
+  const awaiting = finishPlanGeneration(
+    startPlanGeneration("Build a hello world script", "auto-edit"),
+    "Plan v1",
+    "C:\\Workspace\\.codexa\\last-plan.md",
+  );
+  const collecting = beginPlanFeedback(awaiting, "constraints");
+  const generating = submitPlanFeedback(collecting, "Do not touch any other files.");
+
+  assert.equal(generating.kind, "generating");
+  assert.deepEqual(generating.constraints, ["Do not touch any other files."]);
+  assert.deepEqual(generating.pendingFeedback, {
+    mode: "constraints",
+    text: "Do not touch any other files.",
+  });
+});
+
+test("canceling feedback returns to the action picker without losing the plan", () => {
+  const awaiting = finishPlanGeneration(
+    startPlanGeneration("Build a hello world script", "auto-edit"),
+    "Plan v1",
+    "C:\\Workspace\\.codexa\\last-plan.md",
+  );
+  const collecting = beginPlanFeedback(awaiting, "revise");
+  const canceled = cancelPlanFeedback(collecting);
+
+  assert.equal(canceled.kind, "awaiting_action");
+  assert.equal(canceled.currentPlan, "Plan v1");
+  assert.equal(canceled.planFilePath, "C:\\Workspace\\.codexa\\last-plan.md");
+});
+
+test("approving execution moves to executing and reset returns to idle", () => {
+  const awaiting = finishPlanGeneration(
+    startPlanGeneration("Build a hello world script", "auto-edit"),
+    "Plan v1",
+    "C:\\Workspace\\.codexa\\last-plan.md",
+  );
+  const executing = approvePlanExecution(awaiting);
+
+  assert.equal(executing.kind, "executing");
+  assert.equal(executing.executionMode, "auto-edit");
+  assert.equal(executing.planFilePath, "C:\\Workspace\\.codexa\\last-plan.md");
+  assert.deepEqual(resetPlanFlow(), { kind: "idle" });
+});

package/src/session/planFlow.ts

@@ -0,0 +1,149 @@
+import type { AvailableMode } from "../config/settings.js";
+
+export type PlanFeedbackMode = "revise" | "constraints";
+
+export interface PlanFeedbackRequest {
+  mode: PlanFeedbackMode;
+  text: string;
+}
+
+interface PlanFlowContext {
+  originalPrompt: string;
+  executionMode: AvailableMode;
+  constraints: string[];
+  planFilePath: string | null;
+}
+
+export type PlanFlowState =
+  | { kind: "idle" }
+  | (PlanFlowContext & {
+    kind: "generating";
+    currentPlan: string | null;
+    pendingFeedback: PlanFeedbackRequest | null;
+  })
+  | (PlanFlowContext & {
+    kind: "awaiting_action";
+    currentPlan: string;
+  })
+  | (PlanFlowContext & {
+    kind: "collecting_feedback";
+    currentPlan: string;
+    mode: PlanFeedbackMode;
+  })
+  | (PlanFlowContext & {
+    kind: "executing";
+    currentPlan: string;
+  });
+
+export type PlanGeneratingState = Extract<PlanFlowState, { kind: "generating" }>;
+export type PlanAwaitingActionState = Extract<PlanFlowState, { kind: "awaiting_action" }>;
+export type PlanCollectingFeedbackState = Extract<PlanFlowState, { kind: "collecting_feedback" }>;
+export type PlanExecutingState = Extract<PlanFlowState, { kind: "executing" }>;
+
+export function createInitialPlanFlowState(): PlanFlowState {
+  return { kind: "idle" };
+}
+
+export function startPlanGeneration(originalPrompt: string, executionMode: AvailableMode): PlanGeneratingState {
+  return {
+    kind: "generating",
+    originalPrompt,
+    executionMode,
+    constraints: [],
+    planFilePath: null,
+    currentPlan: null,
+    pendingFeedback: null,
+  };
+}
+
+export function finishPlanGeneration(
+  state: PlanFlowState,
+  currentPlan: string,
+  planFilePath: string | null,
+): PlanFlowState {
+  if (state.kind !== "generating") {
+    return state;
+  }
+
+  return {
+    kind: "awaiting_action",
+    originalPrompt: state.originalPrompt,
+    executionMode: state.executionMode,
+    constraints: state.constraints,
+    currentPlan,
+    planFilePath,
+  };
+}
+
+export function beginPlanFeedback(state: PlanFlowState, mode: PlanFeedbackMode): PlanFlowState {
+  if (state.kind !== "awaiting_action") {
+    return state;
+  }
+
+  return {
+    kind: "collecting_feedback",
+    originalPrompt: state.originalPrompt,
+    executionMode: state.executionMode,
+    constraints: state.constraints,
+    currentPlan: state.currentPlan,
+    planFilePath: state.planFilePath,
+    mode,
+  };
+}
+
+export function submitPlanFeedback(state: PlanFlowState, text: string): PlanFlowState {
+  if (state.kind !== "collecting_feedback") {
+    return state;
+  }
+
+  const nextConstraints = state.mode === "constraints"
+    ? [...state.constraints, text]
+    : state.constraints;
+
+  return {
+    kind: "generating",
+    originalPrompt: state.originalPrompt,
+    executionMode: state.executionMode,
+    constraints: nextConstraints,
+    planFilePath: state.planFilePath,
+    currentPlan: state.currentPlan,
+    pendingFeedback: {
+      mode: state.mode,
+      text,
+    },
+  };
+}
+
+export function cancelPlanFeedback(state: PlanFlowState): PlanFlowState {
+  if (state.kind !== "collecting_feedback") {
+    return state;
+  }
+
+  return {
+    kind: "awaiting_action",
+    originalPrompt: state.originalPrompt,
+    executionMode: state.executionMode,
+    constraints: state.constraints,
+    currentPlan: state.currentPlan,
+    planFilePath: state.planFilePath,
+  };
+}
+
+export function approvePlanExecution(state: PlanFlowState): PlanFlowState {
+  if (state.kind !== "awaiting_action") {
+    return state;
+  }
+
+  return {
+    kind: "executing",
+    originalPrompt: state.originalPrompt,
+    executionMode: state.executionMode,
+    constraints: state.constraints,
+    currentPlan: state.currentPlan,
+    planFilePath: state.planFilePath,
+  };
+}
+
+export function resetPlanFlow(): PlanFlowState {
+  return createInitialPlanFlowState();
+}