@golba98/codexa 1.0.1

package/src/core/providerRuntime/types.ts

@@ -0,0 +1,103 @@
+import type { ReasoningEffortCapability } from "../models/codexModelCapabilities.js";
+import type { ProjectInstructions } from "../projectInstructions.js";
+import type { BackendRunHandlers } from "../providers/types.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+export type { ResolvedRuntimeConfig };
+import type { ProviderId } from "../providerLauncher/types.js";
+import type { ProviderWorkspaceOverride } from "../providerLauncher/types.js";
+
+export type ProviderBackendKind =
+  | "codex-cli-auth"
+  | "gemini-cli-auth"
+  | "claude-code-auth"
+  | "openai-api-key"
+  | "gemini-api-key"
+  | "anthropic-api-key"
+  | "local-openai-compatible"
+  | "unavailable";
+
+export interface ProviderModel {
+  id: string;
+  modelId: string;
+  label: string;
+  description: string | null;
+  defaultReasoningLevel: string | null;
+  supportedReasoningLevels: readonly ReasoningEffortCapability[] | null;
+  source?: "discovered" | "claude-code" | "settings" | "config" | "fallback";
+  canonicalId?: string;
+  family?: string;
+  effortSource?: "claude-code" | "settings" | "config" | "fallback";
+  effortVerified?: boolean;
+  raw?: unknown;
+}
+
+export interface ProviderModelDiscoveryResult {
+  status: "ready" | "not-configured";
+  providerId: ProviderId;
+  backendKind: ProviderBackendKind;
+  models: readonly ProviderModel[];
+  message?: string;
+  diagnostics?: Record<string, string | number | boolean | null>;
+}
+
+export type GeminiModelFamily = "gemini-3" | "gemini-2.5";
+
+export type GeminiModelSelection =
+  | { kind: "auto"; family: GeminiModelFamily }
+  | { kind: "manual"; modelId: string };
+
+export interface ProviderRoute {
+  providerId: ProviderId;
+  modelId: string;
+  backendKind: ProviderBackendKind;
+  reasoning?: string;
+  modelSelection?: GeminiModelSelection;
+}
+
+export type ActiveProviderRoute = ProviderRoute;
+
+export interface ProviderRouteValidationRequest {
+  route: ProviderRoute;
+  workspaceRoot: string;
+  geminiCommandPath?: string | null;
+  claudeCommandPath?: string | null;
+  localConfig?: ProviderWorkspaceOverride | null;
+}
+
+export interface ProviderRouteValidationResult {
+  status: "ready" | "not-configured";
+  providerId: ProviderId;
+  backendKind: ProviderBackendKind;
+  message?: string;
+  diagnostics?: Record<string, string | number | boolean | null>;
+}
+
+export interface ProviderChatRequest {
+  prompt: string;
+  route: ProviderRoute;
+  runtime: ResolvedRuntimeConfig;
+  workspaceRoot: string;
+  projectInstructions?: ProjectInstructions | null;
+  localConfig?: ProviderWorkspaceOverride | null;
+}
+
+export interface ProviderChatResponse {
+  text: string;
+  rawOutput?: string;
+}
+
+export interface ProviderRuntime {
+  providerId: ProviderId;
+  label: string;
+  modelPickerLabel?: string;
+  backendKind: ProviderBackendKind;
+  routeAvailable: boolean;
+  routeStatus: string;
+  routeSetupMessage?: string;
+  launchAvailable: boolean;
+  isRouteConfigured?: () => boolean;
+  validateRoute?: (request: ProviderRouteValidationRequest) => Promise<ProviderRouteValidationResult>;
+  discoverModels: () => ProviderModelDiscoveryResult;
+  refreshModels?: (options: { cwd: string; localConfig?: ProviderWorkspaceOverride | null }) => Promise<ProviderModelDiscoveryResult>;
+  run?: (request: ProviderChatRequest, handlers: BackendRunHandlers) => () => void;
+}

package/src/core/providers/codexJsonStream.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { BackendProgressUpdate } from "./types.js";
+import type { RunToolActivity } from "../../session/types.js";
+import { createCodexJsonStreamParser } from "./codexJsonStream.js";
+
+test("streams incremental agent_message growth as assistant deltas", () => {
+  const assistant: string[] = [];
+  const observedFinalAnswers: string[] = [];
+  const parser = createCodexJsonStreamParser({
+    onAssistantDelta: (chunk) => assistant.push(chunk),
+    onFinalAnswerObserved: (response) => observedFinalAnswers.push(response),
+  });
+
+  assert.equal(parser.feedLine(JSON.stringify({
+    type: "item.started",
+    item: { id: "msg-1", type: "agent_message", text: "Hello" },
+  })), true);
+  assert.equal(parser.feedLine(JSON.stringify({
+    type: "item.updated",
+    item: { id: "msg-1", type: "agent_message", text: "Hello world" },
+  })), true);
+  assert.equal(parser.feedLine(JSON.stringify({
+    type: "item.completed",
+    item: { id: "msg-1", type: "agent_message", text: "Hello world!" },
+  })), true);
+  assert.equal(parser.feedLine(JSON.stringify({
+    type: "turn.completed",
+  })), true);
+
+  assert.deepEqual(assistant, ["Hello", " world", "!"]);
+  assert.deepEqual(observedFinalAnswers, ["Hello world!"]);
+  assert.equal(parser.getFinalResponse(), "Hello world!");
+});
+
+test("surfaces command execution lifecycle as tool activity", () => {
+  const toolActivities: RunToolActivity[] = [];
+  const parser = createCodexJsonStreamParser({
+    onToolActivity: (activity) => toolActivities.push(activity),
+  });
+
+  parser.feedLine(JSON.stringify({
+    type: "item.started",
+    item: {
+      id: "cmd-1",
+      type: "command_execution",
+      command: "rg --files",
+      status: "in_progress",
+      aggregated_output: "",
+    },
+  }));
+  parser.feedLine(JSON.stringify({
+    type: "item.completed",
+    item: {
+      id: "cmd-1",
+      type: "command_execution",
+      command: "rg --files",
+      status: "completed",
+      aggregated_output: "src/app.tsx\nsrc/ui/Timeline.tsx\n",
+      exit_code: 0,
+    },
+  }));
+
+  assert.equal(toolActivities.length, 2);
+  assert.equal(toolActivities[0]?.status, "running");
+  assert.equal(toolActivities[0]?.command, "rg --files");
+  assert.equal(toolActivities[1]?.status, "completed");
+  assert.match(toolActivities[1]?.summary ?? "", /src\/app\.tsx/i);
+});
+
+test("emits progress updates for todo_list and reasoning items", () => {
+  const progress: BackendProgressUpdate[] = [];
+  const parser = createCodexJsonStreamParser({
+    onProgress: (update) => progress.push(update),
+  });
+
+  parser.feedLine(JSON.stringify({
+    type: "item.updated",
+    item: {
+      id: "todo-1",
+      type: "todo_list",
+      items: [
+        { text: "Inspect workspace", completed: true },
+        { text: "Write file", completed: false },
+      ],
+    },
+  }));
+  parser.feedLine(JSON.stringify({
+    type: "item.updated",
+    item: {
+      id: "reason-1",
+      type: "reasoning",
+      text: "Verifying the generated output\n\nChecking edge cases",
+    },
+  }));
+
+  assert.deepEqual(progress, [
+    { id: "todo-1", source: "todo", text: "Todo 1/2: Write file" },
+    { id: "reason-1", source: "reasoning", text: "Verifying the generated output\n\nChecking edge cases" },
+  ]);
+});
+
+test("reuses the same progress id when a structured update grows", () => {
+  const progress: BackendProgressUpdate[] = [];
+  const parser = createCodexJsonStreamParser({
+    onProgress: (update) => progress.push(update),
+  });
+
+  parser.feedLine(JSON.stringify({
+    type: "item.updated",
+    item: {
+      id: "reason-7",
+      type: "reasoning",
+      text: "Inspecting the config",
+    },
+  }));
+  parser.feedLine(JSON.stringify({
+    type: "item.updated",
+    item: {
+      id: "reason-7",
+      type: "reasoning",
+      text: "Inspecting the config\n\nComparing runtime defaults",
+    },
+  }));
+
+  assert.deepEqual(progress, [
+    { id: "reason-7", source: "reasoning", text: "Inspecting the config" },
+    { id: "reason-7", source: "reasoning", text: "Inspecting the config\n\nComparing runtime defaults" },
+  ]);
+});
+
+test("captures turn failures from structured events", () => {
+  const parser = createCodexJsonStreamParser({});
+
+  parser.feedLine(JSON.stringify({
+    type: "turn.failed",
+    error: { message: "Permission denied" },
+  }));
+
+  assert.equal(parser.getFailureMessage(), "Permission denied");
+});
+
+test("returns false for non-json lines so callers can fall back to transcript parsing", () => {
+  const parser = createCodexJsonStreamParser({});
+
+  assert.equal(parser.feedLine("assistant"), false);
+  assert.equal(parser.hasStructuredEvents(), false);
+});

package/src/core/providers/codexJsonStream.ts

@@ -0,0 +1,305 @@
+import type { BackendProgressUpdate } from "./types.js";
+import type { RunToolActivity } from "../../session/types.js";
+
+type CodexThreadEvent =
+  | { type: "thread.started"; thread_id: string }
+  | { type: "turn.started" }
+  | { type: "turn.completed"; usage?: { input_tokens?: number; cached_input_tokens?: number; output_tokens?: number } }
+  | { type: "turn.failed"; error?: { message?: string } }
+  | { type: "error"; message?: string }
+  | { type: "item.started" | "item.updated" | "item.completed"; item: CodexThreadItem };
+
+type CodexThreadItem =
+  | {
+    id: string;
+    type: "agent_message";
+    text: string;
+  }
+  | {
+    id: string;
+    type: "reasoning";
+    text: string;
+  }
+  | {
+    id: string;
+    type: "command_execution";
+    command: string;
+    status: "in_progress" | "completed" | "failed";
+    aggregated_output?: string;
+    exit_code?: number;
+  }
+  | {
+    id: string;
+    type: "mcp_tool_call";
+    server: string;
+    tool: string;
+    status: "in_progress" | "completed" | "failed";
+    error?: { message?: string };
+  }
+  | {
+    id: string;
+    type: "web_search";
+    query: string;
+  }
+  | {
+    id: string;
+    type: "todo_list";
+    items: Array<{ text: string; completed: boolean }>;
+  }
+  | {
+    id: string;
+    type: "file_change";
+    changes: Array<{ path: string; kind: "add" | "delete" | "update" }>;
+    status: "completed" | "failed";
+  }
+  | {
+    id: string;
+    type: "error";
+    message: string;
+  };
+
+export interface CodexJsonStreamHandlers {
+  onAssistantDelta?: (chunk: string) => void;
+  onFinalAnswerObserved?: (response: string) => void;
+  onProgress?: (update: BackendProgressUpdate) => void;
+  onToolActivity?: (activity: RunToolActivity) => void;
+}
+
+function normalizeProgressText(text: string | undefined): string | null {
+  if (!text) return null;
+  const normalized = text
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+  return normalized || null;
+}
+
+function firstMeaningfulLine(text: string | undefined): string | null {
+  if (!text) return null;
+  const line = text
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .split("\n")
+    .map((part) => part.trim())
+    .find(Boolean);
+  return line ?? null;
+}
+
+function summarizeCommandExecution(item: Extract<CodexThreadItem, { type: "command_execution" }>): string {
+  const firstLine = firstMeaningfulLine(item.aggregated_output);
+  if (item.status === "failed") {
+    if (firstLine) return firstLine;
+    if (item.exit_code != null) return `Exit code ${item.exit_code}`;
+    return "Failed";
+  }
+  if (firstLine) return firstLine;
+  if (item.exit_code != null) return `Exit code ${item.exit_code}`;
+  return item.status === "completed" ? "Completed" : "Running";
+}
+
+function summarizeTodoList(item: Extract<CodexThreadItem, { type: "todo_list" }>): string | null {
+  if (!item.items.length) return null;
+  const completedCount = item.items.filter((entry) => entry.completed).length;
+  const nextPending = item.items.find((entry) => !entry.completed);
+  if (nextPending) {
+    return `Todo ${completedCount}/${item.items.length}: ${nextPending.text}`;
+  }
+  return `Todo ${completedCount}/${item.items.length}: all tasks complete`;
+}
+
+function summarizeReasoning(item: Extract<CodexThreadItem, { type: "reasoning" }>): string | null {
+  return normalizeProgressText(item.text);
+}
+
+function summarizeFileChange(item: Extract<CodexThreadItem, { type: "file_change" }>): string | null {
+  if (!item.changes.length) return null;
+  const [first] = item.changes;
+  if (item.changes.length === 1 && first) {
+    const verb = first.kind === "add" ? "Created" : first.kind === "delete" ? "Deleted" : "Updated";
+    return `${verb} ${first.path}`;
+  }
+  return `Applied ${item.changes.length} file changes`;
+}
+
+function mapToolActivity(item: Extract<CodexThreadItem, {
+  type: "command_execution" | "mcp_tool_call" | "web_search";
+}>, phase: "item.started" | "item.updated" | "item.completed", existing: RunToolActivity | undefined): RunToolActivity {
+  const startedAt = existing?.startedAt ?? Date.now();
+
+  if (item.type === "command_execution") {
+    const status = item.status === "in_progress" ? "running" : item.status;
+    return {
+      id: item.id,
+      command: item.command,
+      status,
+      startedAt,
+      completedAt: status === "running" ? null : Date.now(),
+      summary: status === "running" ? undefined : summarizeCommandExecution(item),
+    };
+  }
+
+  if (item.type === "mcp_tool_call") {
+    return {
+      id: item.id,
+      command: `${item.server}:${item.tool}`,
+      status: item.status === "in_progress" ? "running" : item.status,
+      startedAt,
+      completedAt: item.status === "in_progress" ? null : Date.now(),
+      summary: item.status === "failed"
+        ? item.error?.message ?? "Failed"
+        : item.status === "completed"
+          ? "Completed"
+          : undefined,
+    };
+  }
+
+  return {
+    id: item.id,
+    command: `web search: ${item.query}`,
+    status: phase === "item.completed" ? "completed" : "running",
+    startedAt,
+    completedAt: phase === "item.completed" ? Date.now() : null,
+    summary: phase === "item.completed" ? "Completed" : undefined,
+  };
+}
+
+export function createCodexJsonStreamParser(handlers: CodexJsonStreamHandlers) {
+  const assistantTextById = new Map<string, string>();
+  const progressTextById = new Map<string, string>();
+  const toolActivityById = new Map<string, RunToolActivity>();
+  let sawEvent = false;
+  let finalResponse = "";
+  let finalAnswerObserved = false;
+  let failureMessage: string | null = null;
+
+  const emitProgress = (
+    key: string,
+    source: BackendProgressUpdate["source"],
+    summary: string | null | undefined,
+  ) => {
+    const next = normalizeProgressText(summary ?? "");
+    if (!next) return;
+    if (progressTextById.get(key) === next) return;
+    progressTextById.set(key, next);
+    handlers.onProgress?.({ id: key, source, text: next });
+  };
+
+  // Codex JSON stream sends cumulative text per item ID rather than deltas.
+  // We track the last emitted text and emit only the newly appended suffix.
+  const emitAssistantText = (itemId: string, nextText: string) => {
+    const previous = assistantTextById.get(itemId) ?? "";
+    assistantTextById.set(itemId, nextText);
+    finalResponse = nextText;
+
+    if (!nextText) return;
+    if (!previous) {
+      handlers.onAssistantDelta?.(nextText);
+      return;
+    }
+
+    if (nextText.startsWith(previous)) {
+      const delta = nextText.slice(previous.length);
+      if (delta) {
+        handlers.onAssistantDelta?.(delta);
+      }
+    }
+  };
+
+  const upsertTool = (item: Extract<CodexThreadItem, {
+    type: "command_execution" | "mcp_tool_call" | "web_search";
+  }>, phase: "item.started" | "item.updated" | "item.completed") => {
+    const next = mapToolActivity(item, phase, toolActivityById.get(item.id));
+    toolActivityById.set(item.id, next);
+    handlers.onToolActivity?.(next);
+  };
+
+  const handleItem = (phase: "item.started" | "item.updated" | "item.completed", item: CodexThreadItem) => {
+    switch (item.type) {
+      case "agent_message":
+        emitAssistantText(item.id, item.text ?? "");
+        break;
+      case "reasoning":
+        emitProgress(item.id, "reasoning", summarizeReasoning(item));
+        break;
+      case "todo_list":
+        emitProgress(item.id, "todo", summarizeTodoList(item));
+        break;
+      case "command_execution":
+        upsertTool(item, phase);
+        emitProgress(item.id, "tool", item.status === "in_progress" ? `Running ${item.command}` : summarizeCommandExecution(item));
+        break;
+      case "mcp_tool_call":
+        upsertTool(item, phase);
+        emitProgress(
+          item.id,
+          "tool",
+          item.status === "in_progress" ? `Calling ${item.server}:${item.tool}` : item.error?.message ?? `Completed ${item.server}:${item.tool}`,
+        );
+        break;
+      case "web_search":
+        upsertTool(item, phase);
+        emitProgress(item.id, "tool", `Searching web: ${item.query}`);
+        break;
+      case "file_change":
+        emitProgress(item.id, "activity", summarizeFileChange(item));
+        break;
+      case "error":
+        failureMessage = item.message;
+        break;
+    }
+  };
+
+  return {
+    feedLine(line: string): boolean {
+      const trimmed = line.trim();
+      if (!trimmed) return false;
+
+      let event: CodexThreadEvent;
+      try {
+        event = JSON.parse(trimmed) as CodexThreadEvent;
+      } catch {
+        return false;
+      }
+
+      if (!event || typeof event !== "object" || typeof event.type !== "string") {
+        return false;
+      }
+
+      sawEvent = true;
+
+      switch (event.type) {
+        case "item.started":
+        case "item.updated":
+        case "item.completed":
+          handleItem(event.type, event.item);
+          break;
+        case "turn.completed":
+          if (!finalAnswerObserved && finalResponse) {
+            finalAnswerObserved = true;
+            handlers.onFinalAnswerObserved?.(finalResponse);
+          }
+          break;
+        case "turn.failed":
+          failureMessage = event.error?.message ?? "Turn failed";
+          break;
+        case "error":
+          failureMessage = event.message ?? "Stream error";
+          break;
+        default:
+          break;
+      }
+
+      return true;
+    },
+    getFinalResponse(): string {
+      return finalResponse;
+    },
+    getFailureMessage(): string | null {
+      return failureMessage;
+    },
+    hasStructuredEvents(): boolean {
+      return sawEvent;
+    },
+  };
+}

package/src/core/providers/codexSubprocess.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+test("codex subprocess attaches output handlers before writing stdin", () => {
+  const source = readFileSync(fileURLToPath(new URL("./codexSubprocess.ts", import.meta.url)), "utf8");
+  const spawnIndex = source.indexOf("proc = spawnCodexProcess");
+  const stdoutIndex = source.indexOf('proc.stdout?.on("data"', spawnIndex);
+  const stderrIndex = source.indexOf('proc.stderr?.on("data"', spawnIndex);
+  const closeIndex = source.indexOf('proc.on("close"', spawnIndex);
+  const errorIndex = source.indexOf('proc.on("error"', spawnIndex);
+  const stdinWriteIndex = source.indexOf("proc.stdin?.write", spawnIndex);
+
+  assert.notEqual(spawnIndex, -1);
+  assert.notEqual(stdoutIndex, -1);
+  assert.notEqual(stderrIndex, -1);
+  assert.notEqual(closeIndex, -1);
+  assert.notEqual(errorIndex, -1);
+  assert.notEqual(stdinWriteIndex, -1);
+  assert.ok(stdoutIndex < stdinWriteIndex);
+  assert.ok(stderrIndex < stdinWriteIndex);
+  assert.ok(closeIndex < stdinWriteIndex);
+  assert.ok(errorIndex < stdinWriteIndex);
+});
+
+test("codex subprocess supports raw prompt passthrough before wrapped prompt fallback", () => {
+  const source = readFileSync(fileURLToPath(new URL("./codexSubprocess.ts", import.meta.url)), "utf8");
+
+  assert.match(source, /const promptPolicy = options\.promptPolicy \?\? "wrapped"/);
+  assert.match(source, /promptPolicy === "raw"\s+\?\s+prompt\s+:\s+buildCodexPrompt/s);
+});
+
+test("codex subprocess cleanup skips kill after process close", () => {
+  const source = readFileSync(fileURLToPath(new URL("./codexSubprocess.ts", import.meta.url)), "utf8");
+  const closeIndex = source.indexOf('proc.on("close"', source.indexOf("proc = spawnCodexProcess"));
+  const exitedIndex = source.indexOf("procExited = true", closeIndex);
+  const cleanupIndex = source.indexOf("return () =>", exitedIndex);
+  const skipIndex = source.indexOf("!proc || procExited || proc.killed", cleanupIndex);
+  const killIndex = source.indexOf("proc.kill()", cleanupIndex);
+
+  assert.notEqual(closeIndex, -1);
+  assert.notEqual(exitedIndex, -1);
+  assert.notEqual(cleanupIndex, -1);
+  assert.notEqual(skipIndex, -1);
+  assert.notEqual(killIndex, -1);
+  assert.ok(exitedIndex < cleanupIndex);
+  assert.ok(skipIndex < killIndex);
+});
+
+test("codex subprocess reports lifecycle boundaries for terminal title reassertion", () => {
+  const source = readFileSync(fileURLToPath(new URL("./codexSubprocess.ts", import.meta.url)), "utf8");
+  const beforeSpawnIndex = source.indexOf('handlers.onProcessLifecycle?.("before-spawn")');
+  const spawnIndex = source.indexOf("proc = spawnCodexProcess");
+  const spawnedIndex = source.indexOf('handlers.onProcessLifecycle?.("spawned")', spawnIndex);
+  const closeIndex = source.indexOf('proc.on("close"', spawnIndex);
+  const exitIndex = source.indexOf('handlers.onProcessLifecycle?.("exit")', closeIndex);
+  const errorIndex = source.indexOf('proc.on("error"', spawnIndex);
+  const lifecycleErrorIndex = source.indexOf('handlers.onProcessLifecycle?.("error")', errorIndex);
+  const cleanupIndex = source.indexOf("return () =>", spawnedIndex);
+  const lifecycleCleanupIndex = source.indexOf('handlers.onProcessLifecycle?.("cleanup")', cleanupIndex);
+
+  assert.ok(beforeSpawnIndex >= 0 && beforeSpawnIndex < spawnIndex);
+  assert.ok(spawnedIndex > spawnIndex);
+  assert.ok(exitIndex > closeIndex);
+  assert.ok(lifecycleErrorIndex > errorIndex);
+  assert.ok(lifecycleCleanupIndex > cleanupIndex);
+});