@golba98/codexa 1.0.2 → 1.0.4

package/src/commands/handler.ts

@@ -36,7 +36,7 @@ import {
   type WorkspaceDisplayMode,
 } from "../config/settings.js";
 
-import type { WorkspaceCommandContext } from "../core/launchContext.js";
+import type { WorkspaceCommandContext } from "../core/workspace/launchContext.js";
 import {
   findModelCapability,
   formatModelCapabilitiesList,
@@ -120,7 +120,7 @@ export interface CommandContext {
   modelCapabilities?: CodexModelCapabilities | null;
   routeStatusMessage?: string;
   activeRouteProviderLabel?: string;
-  projectInstructions?: import("../core/projectInstructions.js").ProjectInstructionsLoadResult | null;
+  projectInstructions?: import("../core/workspace/projectInstructions.js").ProjectInstructionsLoadResult | null;
 }
 
 // Mirrors AVAILABLE_APPROVAL_POLICIES[].id from runtimeConfig.ts
@@ -398,10 +398,10 @@ function buildHelpMessage(context: CommandContext): string {
     "  /copy              Copy last response to clipboard",
     "  /update [check]    Show update status and instructions for updating Codexa",
     "  /help              Show this help",
-    "",
-    "Install on Windows:",
-    "  npm link           Make the codexa command available",
-    "  where codexa       Verify the command resolves",
+    "",
+    "Local development:",
+    "  npm run install:dev-bin  Install the codexa-dev command",
+    "  codexa-dev               Run this repo without replacing codexa",
     "",
     "Shortcuts:",
     "  Ctrl+B    Open backend picker",

package/src/config/buildInfo.ts

@@ -1,3 +1,3 @@
 // Generated by scripts/gen-build-info.mjs — do not edit manually.
-export const BUILD_COMMIT = "6ef3a8a85efef3a525472973403a628a84804c4d" as const;
-export const BUILD_VERSION = "1.0.2" as const;
+export const BUILD_COMMIT = "b066a15b77696d2a0945ea7c6c3d07630584296b" as const;
+export const APP_VERSION = "1.0.4" as const;

package/src/config/layeredConfig.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { normalizeWorkspaceRoot } from "../core/workspaceRoot.js";
+import { normalizeWorkspaceRoot } from "../core/workspace/workspaceRoot.js";
 import {
   formatApprovalPolicyLabel,
   formatNetworkAccessLabel,

package/src/config/persistence.ts

@@ -50,6 +50,7 @@ export interface AuthSettings {
 export interface UpdateCheckSettings {
   enabled: boolean;
   intervalHours: number;
+  skippedUpdateVersion?: string | null;
 }
 
 export const DEFAULT_UPDATE_CHECK_SETTINGS: UpdateCheckSettings = {
@@ -125,6 +126,7 @@ function normalizeUpdateCheckSettings(
     intervalHours: typeof input?.intervalHours === "number" && input.intervalHours > 0
       ? input.intervalHours
       : DEFAULT_UPDATE_CHECK_SETTINGS.intervalHours,
+    skippedUpdateVersion: input?.skippedUpdateVersion ?? null,
   };
 }
 
@@ -269,6 +271,11 @@ export function parseSettingsData(data: unknown): AppSettings {
         : typeof updateCheckSource.interval_hours === "number"
           ? updateCheckSource.interval_hours
           : undefined,
+      skippedUpdateVersion: typeof updateCheckSource.skippedUpdateVersion === "string"
+        ? updateCheckSource.skippedUpdateVersion
+        : typeof updateCheckSource.skipped_update_version === "string"
+          ? updateCheckSource.skipped_update_version
+          : null,
     }),
   };
 }
@@ -299,6 +306,9 @@ export function serializeSettings(settings: AppSettings): Record<string, unknown
     update_check: {
       enabled: settings.updateCheck.enabled,
       interval_hours: settings.updateCheck.intervalHours,
+      ...(settings.updateCheck.skippedUpdateVersion != null
+        ? { skipped_update_version: settings.updateCheck.skippedUpdateVersion }
+        : {}),
     },
   };
 }

package/src/config/runtimeConfig.ts

@@ -106,7 +106,7 @@ export interface ResolvedRuntimeConfig {
 export interface RuntimeStatusContext {
   workspaceRoot: string;
   tokensUsed?: number | null;
-  projectInstructions?: import("../core/projectInstructions.js").ProjectInstructionsLoadResult | null;
+  projectInstructions?: import("../core/workspace/projectInstructions.js").ProjectInstructionsLoadResult | null;
 }
 
 export interface RuntimeSummary {

package/src/config/settings.ts

@@ -1,6 +1,5 @@
-import { homedir } from "os";
-import { basename, join, parse, win32 } from "path";
-import { BUILD_VERSION } from "./buildInfo.js";
+import { homedir } from "os";
+import { basename, join, parse, win32 } from "path";
 
 function isWindowsStylePath(p: string): boolean {
   return /^[A-Za-z]:[\\/]/.test(p) || /^\\\\/.test(p);
@@ -10,14 +9,14 @@ function smartJoin(base: string, ...parts: string[]): string {
   return isWindowsStylePath(base) ? win32.join(base, ...parts) : join(base, ...parts);
 }
 
-export const APP_NAME = "Codexa";
-export const APP_VERSION = BUILD_VERSION;
+export { APP_VERSION } from "./buildInfo.js";
+export const APP_NAME = "Codexa";
 export const DEFAULT_BACKEND = "codex-subprocess";
 export const DEFAULT_MODEL = "gpt-5.4";
 export const DEFAULT_MODE = "full-auto";
 export const DEFAULT_REASONING_LEVEL = "high";
 export const DEFAULT_LAYOUT_STYLE = "gemini-shell";
-export const DEFAULT_THEME = "mono";
+export const DEFAULT_THEME = "dark";
 export const DEFAULT_WORKSPACE_DISPLAY_MODE = "dir";
 export const DEFAULT_TERMINAL_TITLE_MODE = "dir";
 export const DEFAULT_SHOW_BUSY_LOADER = true;
@@ -102,7 +101,7 @@ export const TERMINAL_MOUSE_MODES = ["wheel", "selection"] as const;
 
 export type TerminalMouseMode = (typeof TERMINAL_MOUSE_MODES)[number];
 
-export const DEFAULT_TERMINAL_MOUSE_MODE: TerminalMouseMode = "selection";
+export const DEFAULT_TERMINAL_MOUSE_MODE: TerminalMouseMode = "wheel";
 
 export interface SettingOption<TValue extends string> {
   value: TValue;
@@ -265,21 +264,14 @@ export function formatReasoningLabel(reasoning: string): string {
 }
 
 export const AVAILABLE_THEMES = [
+  { id: "dark", label: "Codexa Dark" },
   { id: "purple", label: "Midnight Purple" },
   { id: "mono", label: "Black & White" },
-  { id: "dark", label: "Modern Dark" },
   { id: "black", label: "Codex the Black" },
-  { id: "emerald", label: "Emerald Night" },
-  { id: "solar", label: "Solar Flare" },
-  { id: "cyber", label: "Cyberpunk Neon" },
-  { id: "ocean", label: "Deep Oceanic" },
   { id: "nordic", label: "Nordic Frost" },
-  { id: "green", label: "Terminal Green" },
-  { id: "amber", label: "Terminal Amber" },
-  { id: "vaporwave", label: "Vaporwave Dream" },
   { id: "dracula", label: "Dracula Night" },
   { id: "gruvbox", label: "Gruvbox Hard" },
-  { id: "synthwave", label: "Synthwave '84" },
+  { id: "ocean", label: "Deep Oceanic" },
   { id: "custom", label: "Customize..." },
 ] as const;
 

package/src/config/trustStore.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname } from "path";
 import { getCodexaTrustStoreFile } from "./settings.js";
-import { normalizeWorkspaceRoot } from "../core/workspaceRoot.js";
+import { normalizeWorkspaceRoot } from "../core/workspace/workspaceRoot.js";
 
 interface TrustStoreData {
   trustedProjectRoots: string[];

package/src/config/updateCheckCache.ts

@@ -39,7 +39,25 @@ export function saveUpdateCheckCache(cache: UpdateCheckCache): void {
   }
 }
 
-export function isCacheValid(cache: UpdateCheckCache, intervalHours: number): boolean {
+function stripV(v: string): string {
+  return v.startsWith("v") ? v.slice(1) : v;
+}
+
+/**
+ * Returns true only when the cache is still usable:
+ * - `runningVersion` matches the version the cache was written for (version-mismatch = stale)
+ * - The cache was written within `intervalHours`
+ */
+export function isCacheValid(
+  cache: UpdateCheckCache,
+  intervalHours: number,
+  runningVersion?: string,
+): boolean {
+  if (runningVersion !== undefined) {
+    if (stripV(cache.currentVersion) !== stripV(runningVersion)) {
+      return false;
+    }
+  }
   const maxAgeMs = intervalHours * 60 * 60 * 1000;
   return Date.now() - cache.lastChecked < maxAgeMs;
 }

package/src/core/README.md

@@ -0,0 +1,52 @@
+# `src/core`
+
+Non-UI runtime logic for Codexa: launching backends, talking to provider CLIs,
+terminal I/O, workspace resolution, and supporting utilities. UI lives in `src/ui`,
+app state in `src/session`, config in `src/config`. The top level of `src/core` is
+folders-only — every file lives in a domain folder so the directory stays scannable.
+
+## Folder map
+
+| Folder | Responsibility |
+| --- | --- |
+| `providers/` | **Low-level Codex subprocess I/O.** Spawns the `codex` binary and parses its output (`codexSubprocess`, `codexJsonStream`, `codexTranscript`), plus the backend registry/types and the `openaiNative` stub. |
+| `providerRuntime/` | **Multi-provider runtimes + discovery.** One runtime per provider (`anthropic`, `gemini`, `local`, `antigravity`) behind a shared interface, plus routing (`registry`), model/metadata helpers (`models`, `capabilityProfile`, `contextMetadata`, `reasoning`) and Claude Code discovery. |
+| `providerLauncher/` | **Workspace provider config + CLI launching.** Which provider is active per workspace (`workspaceConfig`), provider UI state (`registry`), and spawning provider CLIs (`launcher`). |
+| `codex/` | Codex CLI launch/prompt assembly: `codexExecArgs`, `codexLaunch`, `codexPrompt`. |
+| `models/` | Codex CLI capability discovery (`codexCapabilities`, `codexModelCapabilities`) and the legacy model-spec service (`modelSpecs`). |
+| `executables/` | Resolve external CLI binaries with PATH/env handling (`executableResolver` + per-CLI resolvers). |
+| `auth/` | Codex auth status probing. |
+| `process/` | Generic process spawning (`CommandRunner`) and executable-path validation. |
+| `terminal/` | Terminal I/O: ANSI sanitize, raw mode / cursor, title sequences, capability detection, and the `/clear` + resize repaint boundary (`clearFrameBoundary`, `inkRenderReset`). |
+| `workspace/` | Workspace resolution and state: `workspaceRoot`, `workspaceGuard`, `workspaceActivity`, `projectInstructions`, `planStorage`, `launchContext`. |
+| `version/` | Build channel / version branding (`channel`) and update checking (`updateCheck`). |
+| `shared/` | Small cross-cutting utilities: `clipboard`, `cleanupFastFail`, `githubDiagnostics`, `attachments`, `hollowResponseFormat`. |
+| `perf/` | Performance + render instrumentation (`profiler`, `renderDebug`). |
+| `debug/` | Dev-only tracing helpers (`inputDebug`). |
+
+## The three provider layers
+
+`providers/`, `providerRuntime/`, and `providerLauncher/` have similar names but are
+distinct layers — they are **not** duplicates:
+
+```
+providerLauncher/   which provider is active for this workspace + how to spawn its CLI
+        │
+providerRuntime/    per-provider runtimes (anthropic/gemini/local/antigravity),
+        │           routing, model discovery, capability/context metadata
+        │
+providers/          low-level Codex subprocess I/O + output parsing
+```
+
+The default Codex backend flows through `providers/`; the other providers are
+implemented as `providerRuntime/` runtimes.
+
+## Debug instrumentation
+
+These are intentional, env-gated diagnostics (not dead code) — keep them named clearly:
+
+- `debug/inputDebug.ts` — stdin state tracing (`CODEXA_DEBUG_INPUT=1`).
+- `perf/renderDebug.ts` — Ink render/flicker tracing (`CODEXA_RENDER_DEBUG=1`). Kept in
+  `perf/` rather than `debug/` because it is imported widely across the UI.
+- `providerRuntime/claudeCodeDiscoveryDebug.ts` — entry point for the
+  `bun run debug:claude-models` script; lives next to the discovery code it exercises.

package/src/core/agent/loop.ts

@@ -0,0 +1,282 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { BackendRunHandlers } from "../providers/types.js";
+import type { ProviderChatRequest } from "../providerRuntime/types.js";
+import { executeAgentTool, type AgentToolResult } from "./tools.js";
+import { parseAgentToolCall, serializeToolResult, type NormalizedAgentToolCall } from "./protocol.js";
+
+export interface AgentChatMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+}
+
+export interface AgentChatResponse {
+  text: string;
+  toolCalls?: readonly NormalizedAgentToolCall[];
+}
+
+export interface RunAgentLoopOptions {
+  request: ProviderChatRequest;
+  handlers: BackendRunHandlers;
+  sendMessages: (messages: readonly AgentChatMessage[], turnIndex: number) => Promise<AgentChatResponse>;
+  includeSystemPrompt: boolean;
+  signal?: AbortSignal;
+  maxToolCalls?: number;
+}
+
+const DEFAULT_MAX_TOOL_CALLS = 10;
+
+function workspaceSummary(workspaceRoot: string): string {
+  const lines = [`Workspace root: ${workspaceRoot}`];
+  try {
+    const entries = readdirSync(workspaceRoot, { withFileTypes: true })
+      .filter((entry) => ![".git", "node_modules", "dist", "build", "coverage"].includes(entry.name))
+      .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`)
+      .sort()
+      .slice(0, 20);
+    if (entries.length > 0) lines.push(`Top-level entries: ${entries.join(", ")}`);
+  } catch {
+    // Tool-based inspection remains available when a shallow summary is unavailable.
+  }
+
+  try {
+    const packageJsonPath = path.join(workspaceRoot, "package.json");
+    if (existsSync(packageJsonPath)) {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as Record<string, unknown>;
+      const name = typeof packageJson.name === "string" ? packageJson.name : null;
+      const description = typeof packageJson.description === "string" ? packageJson.description : null;
+      if (name) lines.push(`Package: ${name}${description ? ` - ${description}` : ""}`);
+    }
+  } catch {
+    // A malformed package.json should not prevent a local chat request.
+  }
+
+  return lines.join("\n");
+}
+
+function localAgentSystemPrompt(request: ProviderChatRequest): string {
+  const hasCargoToml = existsSync(path.join(request.workspaceRoot, "Cargo.toml"));
+  return [
+    `You are an autonomous coding assistant running inside this workspace: ${request.workspaceRoot}`,
+    "You must inspect files with tools before claiming you cannot see them.",
+    "For broad questions about the repository, use the workspace summary below, then inspect with get_workspace_info or list_files before answering when more detail is needed.",
+    "Use tools to create, edit, build, and test when the user asks for workspace changes.",
+    "Do not ask vague clarification questions when the user's intent has an obvious safe implementation.",
+    hasCargoToml
+      ? "Rust workspace note: Cargo.toml exists. Prefer src/main.rs for simple binaries, use cargo check for validation, use cargo run for running, and do not use rustc main.rs unless main.rs is truly at the workspace root."
+      : null,
+    "Use exactly one tool call at a time in this format:",
+    '<tool_call>{"name":"read_file","arguments":{"path":"src/index.tsx"}}</tool_call>',
+    "Available tools: list_files, read_file, write_file, apply_patch, run_shell, get_workspace_info.",
+    "Summarize changed files and commands run in your final answer.",
+    `Workspace summary:\n${workspaceSummary(request.workspaceRoot)}`,
+    request.projectInstructions?.content
+      ? ["Project instructions:", request.projectInstructions.content].join("\n")
+      : null,
+  ].filter(Boolean).join("\n\n");
+}
+
+function buildInitialMessages(request: ProviderChatRequest, includeSystemPrompt: boolean): AgentChatMessage[] {
+  const systemPrompt = localAgentSystemPrompt(request);
+  if (includeSystemPrompt) {
+    return [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: request.prompt },
+    ];
+  }
+
+  return [
+    { role: "user", content: `${systemPrompt}\n\nUser request:\n${request.prompt}` },
+  ];
+}
+
+function toolActivityCommand(result: Pick<AgentToolResult, "tool" | "path" | "paths" | "command">): string {
+  if (result.command) return `${result.tool}: ${result.command}`;
+  if (result.path) return `${result.tool}: ${result.path}`;
+  if (result.paths && result.paths.length > 0) return `${result.tool}: ${result.paths.join(", ")}`;
+  return result.tool;
+}
+
+interface ExecutedCommand {
+  command: string;
+  success: boolean;
+  exitCode?: number | null;
+  durationMs?: number;
+}
+
+interface AgentLoopSummary {
+  changedFiles: Set<string>;
+  commands: ExecutedCommand[];
+  toolResults: AgentToolResult[];
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function toolCallSignature(call: Pick<NormalizedAgentToolCall, "name" | "arguments">): string {
+  return `${call.name}:${stableJson(call.arguments)}`;
+}
+
+function recordToolResult(summary: AgentLoopSummary, result: AgentToolResult): void {
+  for (const file of result.paths ?? []) {
+    if (file) summary.changedFiles.add(file);
+  }
+  if (result.path && (result.tool === "write_file" || result.tool === "apply_patch")) {
+    summary.changedFiles.add(result.path);
+  }
+  if (result.command) {
+    summary.commands.push({
+      command: result.command,
+      success: result.success,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+    });
+  }
+  summary.toolResults.push(result);
+}
+
+function commandStatus(command: ExecutedCommand): string {
+  const status = command.success ? "succeeded" : "failed";
+  const exitCode = command.exitCode === undefined ? "" : `, exit ${command.exitCode ?? "n/a"}`;
+  return `- ${command.command}: ${status}${exitCode}`;
+}
+
+function nextCommand(request: ProviderChatRequest, summary: AgentLoopSummary): string {
+  if (existsSync(path.join(request.workspaceRoot, "Cargo.toml"))) return "cargo run";
+  const lastValidation = [...summary.commands].reverse().find((item) =>
+    /\b(?:cargo check|cargo run|bun test|npm test|bun run typecheck|tsc)\b/.test(item.command)
+  );
+  if (lastValidation) return lastValidation.command;
+  return "bun test";
+}
+
+function synthesizeFinalMessage(request: ProviderChatRequest, summary: AgentLoopSummary, reason: string): string {
+  const files = [...summary.changedFiles].sort();
+  const commandLines = summary.commands.map(commandStatus);
+  return [
+    reason,
+    "",
+    "Files changed:",
+    files.length > 0 ? files.map((file) => `- ${file}`).join("\n") : "- None detected",
+    "",
+    "Commands run:",
+    commandLines.length > 0 ? commandLines.join("\n") : "- None",
+    "",
+    `Next command: ${nextCommand(request, summary)}`,
+  ].join("\n").trim();
+}
+
+async function requestFinalAnswer(options: RunAgentLoopOptions, messages: AgentChatMessage[], toolCallCount: number, reason: string): Promise<string | null> {
+  messages.push({
+    role: "user",
+    content: [
+      reason,
+      "Stop calling tools now. Write the final answer using the tool results already provided.",
+      "Include files changed, commands run, whether they succeeded, and the next command the user can run.",
+    ].join("\n"),
+  });
+  const response = await options.sendMessages(messages, toolCallCount);
+  const parsed = parseAgentToolCall(response.text);
+  return parsed.kind === "final" && parsed.text.trim() ? parsed.text.trim() : null;
+}
+
+export async function runAgentLoop(options: RunAgentLoopOptions): Promise<string> {
+  const maxToolCalls = options.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS;
+  const messages = buildInitialMessages(options.request, options.includeSystemPrompt);
+  let toolCallCount = 0;
+  let previousToolSignature: string | null = null;
+  const summary: AgentLoopSummary = {
+    changedFiles: new Set(),
+    commands: [],
+    toolResults: [],
+  };
+
+  while (true) {
+    if (options.signal?.aborted) {
+      throw new Error("Local agent run was canceled.");
+    }
+
+    const response = await options.sendMessages(messages, toolCallCount);
+    const structuredToolCall = response.toolCalls?.[0] ?? null;
+    const parsed = structuredToolCall
+      ? { kind: "tool_call" as const, ...structuredToolCall, raw: JSON.stringify(structuredToolCall) }
+      : parseAgentToolCall(response.text);
+
+    if (parsed.kind === "final") {
+      return parsed.text.trim();
+    }
+
+    if (toolCallCount >= maxToolCalls) {
+      const reason = `Local agent reached ${maxToolCalls} tool calls without a final answer.`;
+      const final = await requestFinalAnswer(options, messages, toolCallCount, reason);
+      return final ?? synthesizeFinalMessage(options.request, summary, reason);
+    }
+
+    if (parsed.kind === "malformed_tool_call") {
+      messages.push({ role: "assistant", content: response.text });
+      toolCallCount += 1;
+      messages.push({
+        role: "user",
+        content: serializeToolResult({
+          success: false,
+          error: `Malformed tool call: ${parsed.error}`,
+          raw: parsed.raw,
+        }),
+      });
+      continue;
+    }
+
+    const signature = toolCallSignature(parsed);
+    if (signature === previousToolSignature) {
+      const reason = `Local agent repeated the same ${parsed.name} tool call with identical arguments.`;
+      const final = await requestFinalAnswer(options, messages, toolCallCount, reason);
+      return final ?? synthesizeFinalMessage(options.request, summary, reason);
+    }
+
+    messages.push({ role: "assistant", content: response.text || parsed.raw });
+    previousToolSignature = signature;
+    toolCallCount += 1;
+    const activityId = `local-agent-${toolCallCount}-${parsed.name}`;
+    const startedAt = Date.now();
+    const runningCommand = toolActivityCommand({
+      tool: parsed.name,
+      path: typeof parsed.arguments.path === "string" ? parsed.arguments.path : undefined,
+      command: typeof parsed.arguments.command === "string" ? parsed.arguments.command : undefined,
+    });
+    options.handlers.onToolActivity?.({
+      id: activityId,
+      command: runningCommand,
+      status: "running",
+      startedAt,
+    });
+
+    const result = await executeAgentTool(parsed.name, parsed.arguments, {
+      workspaceRoot: options.request.workspaceRoot,
+      runtime: options.request.runtime,
+      signal: options.signal,
+    });
+    const completedCommand = toolActivityCommand(result);
+    options.handlers.onToolActivity?.({
+      id: activityId,
+      command: completedCommand,
+      status: result.success ? "completed" : "failed",
+      startedAt,
+      completedAt: Date.now(),
+      summary: result.summary ?? result.error ?? null,
+    });
+    recordToolResult(summary, result);
+
+    messages.push({
+      role: "user",
+      content: serializeToolResult(result),
+    });
+  }
+
+  throw new Error(`Local agent stopped after ${maxToolCalls} tool calls without a final answer.`);
+}