Merge pull request #197 from asynkron/codex/locate-self-heal.md-62gob4

Fix OpenAI response types and consolidate web panel toggles

Author: rogeralsing

packages/core/src/agent/context.md

@@ -7,7 +7,8 @@
 ## Key Modules
 
 - `loop.ts` (emits `loop.js`) — orchestrates the event-driven runtime: manages plan snapshots, queues inputs/outputs, handles OpenAI calls, applies filters, coordinates cancellation, and enforces a payload-growth failsafe that dumps runaway histories before retrying. The runtime exposes factory hooks (`createOutputsQueueFn`, `createInputsQueueFn`, `createPlanManagerFn`, `createEscStateFn`, `createPromptCoordinatorFn`, `createApprovalManagerFn`) so hosts can inject alternatives without patching the core loop. Additional DI knobs let callers override logging, request cancellation, prompt phrasing, auto-response limits, and downstream pass executor dependencies.
-- `passExecutor.ts` (emits `passExecutor.js`) — coordinates multi-pass reasoning. It requests model completions, parses and validates assistant responses, merges incoming plan data, dispatches shell commands, records observations, nudges the model when plans stall, and syncs plan snapshots back to disk. The helper accepts overridable collaborators for OpenAI calls, command execution, history compaction, observation building, context usage summaries, and schema validation. Supporting utilities live alongside it under `passExecutor/` (plan execution helpers, refusal heuristics) so orchestration logic stays focused on control flow.
+- `passExecutor.ts` (emits `passExecutor.js`) — coordinates multi-pass reasoning. It requests model completions, parses and validates assistant responses, merges incoming plan data, dispatches shell commands, records observations, nudges the model when plans stall, and syncs plan snapshots back to disk. The helper accepts overridable collaborators for OpenAI calls, command execution, history compaction, observation building, context usage summaries, and schema validation. Supporting utilities live alongside it under `passExecutor/` (plan execution helpers, refusal heuristics) so orchestration logic stays focused on control flow, and a small plan-reminder controller now keeps auto-response counters consistent even when hosts omit a tracker implementation. Recent tightening removed `@ts-nocheck`, aligning the module with typed OpenAI clients and DI hooks so build-time checking now covers its glue code.
+ - `passExecutor.ts` (emits `passExecutor.js`) — coordinates multi-pass reasoning. It requests model completions, parses and validates assistant responses, merges incoming plan data, dispatches shell commands, records observations, nudges the model when plans stall, and syncs plan snapshots back to disk. The helper accepts overridable collaborators for OpenAI calls, command execution, history compaction, observation building, context usage summaries, and schema validation. Supporting utilities live alongside it under `passExecutor/` (plan execution helpers, refusal heuristics) so orchestration logic stays focused on control flow, and a small plan-reminder controller now keeps auto-response counters consistent even when hosts omit a tracker implementation. Recent tightening removed `@ts-nocheck`, aligning the module with typed OpenAI clients and DI hooks so build-time checking now covers its glue code, and the plan manager invoker now carries explicit plan argument types instead of falling back to `any`.
 - `approvalManager.ts` (emits `approvalManager.js`) — normalizes the approval policy: checks allowlists/session approvals, optionally prompts the human, and records session grants.
 - `amnesiaManager.ts` (emits `amnesiaManager.js`) — prunes stale history entries and exposes a dementia policy helper that drops messages older than the configured pass threshold.
 - `commandExecution.ts` (emits `commandExecution.js`) and `commands/ExecuteCommand.ts` — normalize assistant command payloads and delegate to the injected shell runner.

packages/core/src/agent/passExecutor.ts

@@ -1,11 +1,10 @@
-// @ts-nocheck
 import { planHasOpenSteps } from '../utils/plan.js';
 import { incrementCommandCount as defaultIncrementCommandCount } from '../services/commandStatsService.js';
 import {
   combineStdStreams as defaultCombineStdStreams,
   buildPreview as defaultBuildPreview,
 } from '../utils/output.js';
-import ObservationBuilder from './observationBuilder.js';
+import ObservationBuilder, { type ObservationBuilderDeps } from './observationBuilder.js';
 import { parseAssistantResponse as defaultParseAssistantResponse } from './responseParser.js';
 import { requestModelCompletion as defaultRequestModelCompletion } from './openaiRequest.js';
 import { executeAgentCommand as defaultExecuteAgentCommand } from './commandExecution.js';
@@ -19,6 +18,7 @@ import {
   createChatMessageEntry as defaultCreateChatMessageEntry,
   type ChatMessageEntry,
 } from './historyEntry.js';
+import type { ResponsesClient } from '../openai/responses.js';
 import {
   createObservationHistoryEntry,
   createPlanReminderEntry,
@@ -55,16 +55,18 @@ interface PlanManagerLike {
   sync?: (plan: PlanStep[] | null | undefined) => Promise<unknown>;
 }
 
-type PlanManagerMethod = ((...args: unknown[]) => unknown) | null | undefined;
+type PlanManagerMethod = ((plan?: PlanStep[] | null | undefined) => unknown) | null | undefined;
 
 const createPlanManagerInvoker =
   (manager: PlanManagerLike) =>
-  (method: PlanManagerMethod, ...args: unknown[]): unknown => {
+  (method: PlanManagerMethod, plan?: PlanStep[] | null | undefined): unknown => {
     if (typeof method !== 'function') {
       return undefined;
     }
 
-    return method.call(manager, ...args);
+    // Passing an explicit plan argument keeps TypeScript satisfied while still
+    // allowing zero-argument plan manager methods to ignore it at runtime.
+    return method.call(manager, plan);
   };
 
 interface ExecutableCandidate extends ExecutablePlanStep {
@@ -74,14 +76,75 @@ interface ExecutableCandidate extends ExecutablePlanStep {
 
 const PLAN_REMINDER_AUTO_RESPONSE_LIMIT = 3;
 
+interface PlanReminderController {
+  recordAttempt: () => number;
+  reset: () => void;
+  getCount: () => number;
+}
+
+const createPlanReminderController = (
+  tracker: PlanAutoResponseTracker | null | undefined,
+): PlanReminderController => {
+  if (tracker && typeof tracker.increment === 'function' && typeof tracker.reset === 'function') {
+    return {
+      recordAttempt: () => tracker.increment(),
+      reset: () => tracker.reset(),
+      getCount: () => (typeof tracker.getCount === 'function' ? (tracker.getCount() ?? 0) : 0),
+    };
+  }
+
+  // Fallback tracker keeps local state so the reminder limit still applies even when
+  // the caller does not provide a dedicated tracker implementation.
+  let fallbackCount = 0;
+  return {
+    recordAttempt: () => {
+      fallbackCount += 1;
+      return fallbackCount;
+    },
+    reset: () => {
+      fallbackCount = 0;
+    },
+    getCount: () => fallbackCount,
+  };
+};
+
+const pickNextExecutableCandidate = (entries: ExecutablePlanStep[]): ExecutableCandidate | null => {
+  let best: ExecutableCandidate | null = null;
+
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const candidate: ExecutableCandidate = {
+      ...entry,
+      index,
+      priority: getPriorityScore(entry.step),
+    };
+
+    if (!best) {
+      best = candidate;
+      continue;
+    }
+
+    if (candidate.priority < best.priority) {
+      best = candidate;
+      continue;
+    }
+
+    if (candidate.priority === best.priority && candidate.index < best.index) {
+      best = candidate;
+    }
+  }
+
+  return best;
+};
+
 const normalizeAssistantMessage = (value: unknown): string =>
   typeof value === 'string' ? value.replace(/[\u2018\u2019]/g, "'") : '';
 // Quick heuristic to detect short apology-style refusals so we can auto-nudge the model.
 const isLikelyRefusalMessage = (message: unknown): boolean =>
   refusalHeuristics.isLikelyRefusalMessage(message);
 
 export interface ExecuteAgentPassOptions {
-  openai: unknown;
+  openai: ResponsesClient;
   model: string;
   history: ChatMessageEntry[];
   emitEvent?: (event: UnknownRecord) => void;
@@ -103,14 +166,9 @@ export interface ExecuteAgentPassOptions {
   passIndex: number;
   requestModelCompletionFn?: typeof defaultRequestModelCompletion;
   executeAgentCommandFn?: typeof defaultExecuteAgentCommand;
-  createObservationBuilderFn?: (deps: {
-    combineStdStreams: typeof defaultCombineStdStreams;
-    applyFilter: (text: string, regex: string) => string;
-    tailLines: (text: string, lines: number) => string;
-    buildPreview: typeof defaultBuildPreview;
-  }) => ObservationBuilder;
-  combineStdStreamsFn?: typeof defaultCombineStdStreams;
-  buildPreviewFn?: typeof defaultBuildPreview;
+  createObservationBuilderFn?: (deps: ObservationBuilderDeps) => ObservationBuilder;
+  combineStdStreamsFn?: ObservationBuilderDeps['combineStdStreams'];
+  buildPreviewFn?: ObservationBuilderDeps['buildPreview'];
   parseAssistantResponseFn?: typeof defaultParseAssistantResponse;
   validateAssistantResponseSchemaFn?: typeof defaultValidateAssistantResponseSchema;
   validateAssistantResponseFn?: typeof defaultValidateAssistantResponse;
@@ -152,8 +210,10 @@ export async function executeAgentPass({
   requestModelCompletionFn = defaultRequestModelCompletion,
   executeAgentCommandFn = defaultExecuteAgentCommand,
   createObservationBuilderFn = (deps) => new ObservationBuilder(deps),
-  combineStdStreamsFn = defaultCombineStdStreams,
-  buildPreviewFn = defaultBuildPreview,
+  combineStdStreamsFn = (stdout, stderr, exitCode) =>
+    // Normalize optional exit codes before delegating so ObservationBuilder sees a consistent signature.
+    defaultCombineStdStreams(stdout, stderr, exitCode ?? 0),
+  buildPreviewFn = (text) => defaultBuildPreview(text),
   parseAssistantResponseFn = defaultParseAssistantResponse,
   validateAssistantResponseSchemaFn = defaultValidateAssistantResponseSchema,
   validateAssistantResponseFn = defaultValidateAssistantResponse,
@@ -326,28 +386,7 @@ export async function executeAgentPass({
 
   const parsed = parseResult.value;
 
-  const planAutoResponder =
-    planAutoResponseTracker &&
-    typeof planAutoResponseTracker.increment === 'function' &&
-    typeof planAutoResponseTracker.reset === 'function'
-      ? planAutoResponseTracker
-      : null;
-
-  const incrementPlanReminder = () => {
-    if (!planAutoResponder || typeof planAutoResponder.increment !== 'function') {
-      return 1;
-    }
-
-    return planAutoResponder.increment();
-  };
-
-  const resetPlanReminder = () => {
-    if (!planAutoResponder || typeof planAutoResponder.reset !== 'function') {
-      return;
-    }
-
-    planAutoResponder.reset();
-  };
+  const planReminder = createPlanReminderController(planAutoResponseTracker);
 
   emitDebug(() => ({
     stage: 'assistant-response',
@@ -493,27 +532,8 @@ export async function executeAgentPass({
 
   let planMutatedDuringExecution = false;
 
-  const selectNextExecutableEntry = (): ExecutableCandidate | null => {
-    const candidates = collectExecutablePlanSteps(activePlan).map((entry, index) => ({
-      ...entry,
-      index,
-      priority: getPriorityScore(entry.step),
-    }));
-
-    if (candidates.length === 0) {
-      return null;
-    }
-
-    candidates.sort((a, b) => {
-      if (a.priority === b.priority) {
-        return a.index - b.index;
-      }
-
-      return a.priority - b.priority;
-    });
-
-    return candidates[0] ?? null;
-  };
+  const selectNextExecutableEntry = (): ExecutableCandidate | null =>
+    pickNextExecutableCandidate(collectExecutablePlanSteps(activePlan));
 
   let nextExecutable = selectNextExecutableEntry();
 
@@ -545,15 +565,15 @@ export async function executeAgentPass({
           pass: activePass,
         }),
       );
-      resetPlanReminder();
+      planReminder.reset();
       return true;
     }
 
     const hasOpenSteps =
       Array.isArray(activePlan) && activePlan.length > 0 && planHasOpenSteps(activePlan);
 
     if (hasOpenSteps) {
-      const attempt = incrementPlanReminder();
+      const attempt = planReminder.recordAttempt();
 
       if (attempt <= PLAN_REMINDER_AUTO_RESPONSE_LIMIT) {
         emitEvent({
@@ -570,7 +590,7 @@ export async function executeAgentPass({
 
     if (!activePlanEmpty && !hasOpenSteps) {
       // The plan is finished; wipe the snapshot so follow-up prompts start cleanly.
-      if (invokePlanManager) {
+      if (planManager && invokePlanManager) {
         try {
           const cleared = await invokePlanManager(planManager.reset);
           if (Array.isArray(cleared)) {
@@ -594,11 +614,11 @@ export async function executeAgentPass({
       emitEvent({ type: 'plan', plan: clonePlanForExecution(activePlan) });
     }
 
-    resetPlanReminder();
+    planReminder.reset();
     return false;
   }
 
-  resetPlanReminder();
+  planReminder.reset();
 
   const manageCommandThinking =
     Boolean(nextExecutable) &&
@@ -817,7 +837,7 @@ export async function executeAgentPass({
   if (planMutatedDuringExecution && Array.isArray(activePlan)) {
     emitEvent({ type: 'plan', plan: clonePlanForExecution(activePlan) });
 
-    if (invokePlanManager && typeof planManager?.sync === 'function') {
+    if (planManager && invokePlanManager && typeof planManager.sync === 'function') {
       try {
         await invokePlanManager(planManager.sync, activePlan);
       } catch (error) {

packages/core/src/openai/context.md

@@ -7,7 +7,7 @@
 ## Key Files
 
 - `client.js` — lazily instantiates the OpenAI SDK client based on environment variables, validates models, surfaces setup guidance when configuration is missing, and exposes `MODEL`, `getOpenAIClient`, `resetOpenAIClient`.
-- `responses.js` — constructs structured responses API calls, attaches tool schemas, handles retries, and normalizes errors (now resolving both object- and function-shaped providers returned by the AI SDK) while exposing typed call options so downstream callers no longer rely on defensive runtime checks.
+- `responses.js` — constructs structured responses API calls, attaches tool schemas, handles retries, and normalizes errors (now resolving both object- and function-shaped providers returned by the AI SDK) while exposing typed call options so downstream callers no longer rely on defensive runtime checks. Call settings now use a partial type so default retry/abort behavior compiles cleanly when no overrides are provided.
 - `responseUtils.js` — normalizes OpenAI Responses payloads, exposing helpers to pull the sanitized `open-agent` tool call (for protocol validation) while still providing a text fallback for legacy/plain-text replies.
 
 ## Positive Signals

packages/core/src/openai/responses.ts

@@ -42,7 +42,7 @@ export interface ResponseCallOptions {
   maxRetries?: number;
 }
 
-type ResponseCallSettings = Pick<CallSettings, 'abortSignal' | 'maxRetries'>;
+type ResponseCallSettings = Partial<Pick<CallSettings, 'abortSignal' | 'maxRetries'>>;
 
 function buildCallSettings(options: ResponseCallOptions | undefined): ResponseCallSettings {
   const { maxRetries } = getOpenAIRequestSettings();

packages/core/src/utils/context.md

@@ -11,7 +11,7 @@
 - `contextUsage.ts` — tracks token usage metrics for display in the CLI.
 - `fetch.ts` — thin wrapper around `undici`/`node-fetch` semantics with timeout & error normalization; now prefers the global Fetch API with typed fallbacks to Node's `http`/`https` modules.
 - `jsonAssetValidator.ts` — validates JSON files against provided schemas; leveraged by scripts/tests.
-- `output.ts` — formatting helpers for CLI output and logs, now typed to guarantee string outputs.
+- `output.ts` — formatting helpers for CLI output and logs, now typed to guarantee string outputs. The `combineStdStreams` helper tolerates missing exit codes so observation builders can share the same implementation across typed and untyped callers.
 - `plan.ts` — plan tree clone/merge/progress utilities used by agent runtime & UI.
   - Incoming items with `status: 'abandoned'` now remove the matching plan branch during merge.
   - Steps waiting on dependencies now remain blocked if any dependency failed instead of treating failure as completion.

packages/core/src/utils/output.ts

@@ -10,12 +10,13 @@ export type CombinedStreams = {
 export function combineStdStreams(
   filteredStdout: unknown,
   filteredStderr: unknown,
-  exitCode: number,
+  exitCode: number | null | undefined,
 ): CombinedStreams {
   const stdoutText = filteredStdout != null ? String(filteredStdout) : '';
   const stderrText = filteredStderr != null ? String(filteredStderr) : '';
+  const normalizedExitCode = typeof exitCode === 'number' ? exitCode : 0;
 
-  if (exitCode === 0 && stderrText.trim().length > 0) {
+  if (normalizedExitCode === 0 && stderrText.trim().length > 0) {
     const combined = stdoutText ? `${stdoutText}\n${stderrText}` : stderrText;
     return { stdout: combined, stderr: '' };
   }

packages/web/frontend/context.md

@@ -31,3 +31,4 @@
 - Pruned unused helper typings in shared context/tests so ESLint stays quiet under the expanded repo-wide lint run.
 - Extracted helper utilities inside `services/chat.ts` to normalise event payloads before rendering, reducing duplicated DOM-building logic when displaying agent banners and status messages.
 - `services/chat.ts` now centralises message container creation/append helpers so message, event, and command renders share the same DOM plumbing instead of repeating wrapper scaffolding.
+- Panel activation toggles now share a dedicated helper so conversation start and reset flows reuse the same DOM updates without duplicating focus/visibility logic.

packages/web/frontend/src/js/services/chat.ts

@@ -169,26 +169,30 @@ export function createChatService({
     }
   }
 
-  function ensureConversationStarted(): void {
-    if (hasConversation) {
-      return;
-    }
-    hasConversation = true;
-    panelRef.classList.toggle('agent-panel--empty', false);
+  function setPanelActive(active: boolean): void {
+    panelRef.classList.toggle('agent-panel--empty', !active);
     if (startContainer) {
-      startContainer.classList.toggle('hidden', true);
+      startContainer.classList.toggle('hidden', active);
     }
     if (chatContainer) {
-      chatContainer.classList.toggle('hidden', false);
+      chatContainer.classList.toggle('hidden', !active);
     }
-    if (chatInput) {
+    if (active && chatInput) {
       windowRef.requestAnimationFrame(() => {
         chatInput.focus();
         autoResize(chatInput);
       });
     }
   }
 
+  function ensureConversationStarted(): void {
+    if (hasConversation) {
+      return;
+    }
+    hasConversation = true;
+    setPanelActive(true);
+  }
+
   function ensureThinkingMessage(): void {
     if (!messageList || thinkingMessage) {
       return;
@@ -520,20 +524,7 @@ export function createChatService({
   }
 
   function updatePanelState(): void {
-    const active = hasConversation;
-    panelRef.classList.toggle('agent-panel--empty', !active);
-    if (startContainer) {
-      startContainer.classList.toggle('hidden', active);
-    }
-    if (chatContainer) {
-      chatContainer.classList.toggle('hidden', !active);
-    }
-    if (active && chatInput) {
-      windowRef.requestAnimationFrame(() => {
-        chatInput.focus();
-        autoResize(chatInput);
-      });
-    }
+    setPanelActive(hasConversation);
   }
 
   /**