ubume 0.1.0

package/src/headless/execArgs.ts

@@ -0,0 +1,296 @@
+import type { LaunchArgs } from "../config/launchArgs.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface HeadlessExecArgs {
+  help: boolean;
+  benchmarkDiagnostics: boolean;
+  timing: boolean;
+  promptPolicy: "raw" | "wrapped";
+  prompt: string;
+  launchArgs: LaunchArgs;
+}
+
+export type HeadlessExecArgsParseResult =
+  | { ok: true; value: HeadlessExecArgs }
+  | { ok: false; error: string };
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function normalizeNonEmpty(value: string | undefined): string | null {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function parseConfigFlagValue(raw: string | undefined): string | null {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const separatorIndex = trimmed.indexOf("=");
+  if (separatorIndex <= 0 || separatorIndex === trimmed.length - 1) {
+    return null;
+  }
+
+  return trimmed;
+}
+
+function parseModelFlagValue(raw: string | undefined): string | null {
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : null;
+}
+
+function quoteTomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function buildLaunchArgs(params: {
+  prompt: string | null;
+  profile: string | null;
+  configOverrides: string[];
+  passthroughArgs: string[];
+  modelOverride: string | null;
+}): LaunchArgs {
+  return {
+    help: false,
+    version: false,
+    initialPrompt: params.prompt,
+    profile: params.profile,
+    configOverrides: params.configOverrides,
+    passthroughArgs: params.passthroughArgs,
+    modelOverride: params.modelOverride,
+    noClear: false,
+  };
+}
+
+// ─── Parser ──────────────────────────────────────────────────────────────────
+
+export function parseHeadlessExecArgs(argv: readonly string[]): HeadlessExecArgsParseResult {
+  const configOverrides: string[] = [];
+  const passthroughArgs: string[] = [];
+  const positionalPromptParts: string[] = [];
+  let explicitPrompt: string | null = null;
+  let profile: string | null = null;
+  let modelOverride: string | null = null;
+  let help = false;
+  let benchmarkDiagnostics = false;
+  let timing = false;
+  let promptPolicy: "raw" | "wrapped" = "raw";
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+
+    if (arg === "--benchmark-diagnostics") {
+      benchmarkDiagnostics = true;
+      timing = true;
+      continue;
+    }
+
+    if (arg === "--timing") {
+      timing = true;
+      continue;
+    }
+
+    if (arg === "--skip-git-repo-check") {
+      passthroughArgs.push(arg);
+      continue;
+    }
+
+    // --codexa-prompt-policy is the pre-rename spelling; keep accepting it.
+    if (arg === "--ubume-prompt-policy" || arg === "--codexa-prompt-policy") {
+      const value = normalizeNonEmpty(argv[index + 1]);
+      if (value !== "raw" && value !== "wrapped") {
+        return { ok: false, error: "Missing or invalid value for --ubume-prompt-policy. Use raw or wrapped." };
+      }
+      promptPolicy = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--ubume-prompt-policy=") || arg.startsWith("--codexa-prompt-policy=")) {
+      const value = normalizeNonEmpty(arg.slice(arg.indexOf("=") + 1));
+      if (value !== "raw" && value !== "wrapped") {
+        return { ok: false, error: "Invalid value for --ubume-prompt-policy. Use raw or wrapped." };
+      }
+      promptPolicy = value;
+      continue;
+    }
+
+    if (arg === "--") {
+      positionalPromptParts.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (arg === "--prompt") {
+      const value = normalizeNonEmpty(argv[index + 1]);
+      if (!value) {
+        return { ok: false, error: "Missing value for --prompt." };
+      }
+      explicitPrompt = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--prompt=")) {
+      const value = normalizeNonEmpty(arg.slice("--prompt=".length));
+      if (!value) {
+        return { ok: false, error: "Missing value for --prompt." };
+      }
+      explicitPrompt = value;
+      continue;
+    }
+
+    if (arg === "--profile") {
+      const value = normalizeNonEmpty(argv[index + 1]);
+      if (!value) {
+        return { ok: false, error: "Missing value for --profile." };
+      }
+      profile = value;
+      passthroughArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--profile=")) {
+      const value = normalizeNonEmpty(arg.slice("--profile=".length));
+      if (!value) {
+        return { ok: false, error: "Missing value for --profile." };
+      }
+      profile = value;
+      passthroughArgs.push(`--profile=${value}`);
+      continue;
+    }
+
+    if (arg === "-c" || arg === "--config") {
+      const value = parseConfigFlagValue(argv[index + 1]);
+      if (!value) {
+        return { ok: false, error: `Missing key=value payload for ${arg}.` };
+      }
+      configOverrides.push(value);
+      passthroughArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--config=")) {
+      const value = parseConfigFlagValue(arg.slice("--config=".length));
+      if (!value) {
+        return { ok: false, error: "Missing key=value payload for --config." };
+      }
+      configOverrides.push(value);
+      passthroughArgs.push(`--config=${value}`);
+      continue;
+    }
+
+    if (arg.startsWith("-c=")) {
+      const value = parseConfigFlagValue(arg.slice(3));
+      if (!value) {
+        return { ok: false, error: "Missing key=value payload for -c." };
+      }
+      configOverrides.push(value);
+      passthroughArgs.push(`-c=${value}`);
+      continue;
+    }
+
+    if (arg === "--model" || arg === "-m") {
+      const value = parseModelFlagValue(argv[index + 1]);
+      if (!value) {
+        return { ok: false, error: `Missing value for ${arg}.` };
+      }
+      configOverrides.push(`model=${quoteTomlString(value)}`);
+      passthroughArgs.push(arg, value);
+      modelOverride = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--model=")) {
+      const value = parseModelFlagValue(arg.slice("--model=".length));
+      if (!value) {
+        return { ok: false, error: "Missing value for --model." };
+      }
+      configOverrides.push(`model=${quoteTomlString(value)}`);
+      passthroughArgs.push(`--model=${value}`);
+      modelOverride = value;
+      continue;
+    }
+
+    if (arg === "--reasoning") {
+      const value = parseModelFlagValue(argv[index + 1]);
+      if (!value) {
+        return { ok: false, error: `Missing value for ${arg}.` };
+      }
+      configOverrides.push(`model_reasoning_effort=${value}`);
+      passthroughArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--reasoning=")) {
+      const value = parseModelFlagValue(arg.slice("--reasoning=".length));
+      if (!value) {
+        return { ok: false, error: "Missing value for --reasoning." };
+      }
+      configOverrides.push(`model_reasoning_effort=${value}`);
+      passthroughArgs.push(`--reasoning=${value}`);
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      return { ok: false, error: `Unknown option for ubume exec: ${arg}` };
+    }
+
+    positionalPromptParts.push(arg, ...argv.slice(index + 1));
+    break;
+  }
+
+  const positionalPrompt = positionalPromptParts
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join(" ")
+    .trim() || null;
+
+  if (explicitPrompt && positionalPrompt) {
+    return { ok: false, error: "Provide a prompt either positionally or with --prompt, not both." };
+  }
+
+  const prompt = explicitPrompt ?? positionalPrompt;
+  if (help) {
+    return {
+      ok: true,
+      value: {
+        help,
+        benchmarkDiagnostics,
+        timing,
+        promptPolicy,
+        prompt: prompt ?? "",
+        launchArgs: buildLaunchArgs({ prompt, profile, configOverrides, passthroughArgs, modelOverride }),
+      },
+    };
+  }
+
+  if (!prompt) {
+    return { ok: false, error: "Missing prompt. Use ubume exec \"prompt\" or ubume exec --prompt \"prompt\"." };
+  }
+
+  return {
+    ok: true,
+    value: {
+      help,
+      benchmarkDiagnostics,
+      timing,
+      promptPolicy,
+      prompt,
+      launchArgs: buildLaunchArgs({ prompt, profile, configOverrides, passthroughArgs, modelOverride }),
+    },
+  };
+}

package/src/headless/execRunner.ts

@@ -0,0 +1,304 @@
+import {
+  resolveLayeredConfig,
+  type LayeredConfigResult,
+} from "../config/layeredConfig.js";
+import type { LaunchArgs } from "../config/launchArgs.js";
+import {
+  mergeRuntimeConfig,
+  resolveRuntimeConfig,
+  type ResolvedRuntimeConfig,
+} from "../config/runtimeConfig.js";
+import { loadProjectInstructions, type ProjectInstructionsLoadResult } from "../core/workspace/projectInstructions.js";
+import { getBackendProvider } from "../core/providers/registry.js";
+import type { BackendProvider } from "../core/providers/types.js";
+import { isNoiseLine } from "../core/providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "../core/terminal/terminalSanitize.js";
+import { resolveWorkspaceRoot } from "../core/workspace/workspaceRoot.js";
+import type { RunToolActivity } from "../session/types.js";
+
+// ─── Types & constants ────────────────────────────────────────────────────────
+
+export const HEADLESS_EXEC_PARSE_ERROR = 2;
+export const HEADLESS_EXEC_PROVIDER_UNAVAILABLE = 3;
+export const HEADLESS_EXEC_RUN_FAILED = 1;
+
+export interface HeadlessExecIo {
+  stdout: Pick<NodeJS.WriteStream, "write">;
+  stderr: Pick<NodeJS.WriteStream, "write">;
+}
+
+export interface HeadlessExecOptions {
+  prompt: string;
+  launchArgs: LaunchArgs;
+  workspaceRoot?: string;
+  benchmarkDiagnostics?: HeadlessExecTiming;
+  promptPolicy?: "raw" | "wrapped";
+}
+
+export interface HeadlessExecResult {
+  exitCode: number;
+}
+
+export interface HeadlessExecDependencies {
+  resolveWorkspaceRoot: () => string;
+  resolveLayeredConfig: (options: { workspaceRoot: string; launchArgs: LaunchArgs }) => LayeredConfigResult;
+  resolveRuntimeConfig: typeof resolveRuntimeConfig;
+  getBackendProvider: (id: string) => BackendProvider;
+  loadProjectInstructions: (workspaceRoot: string) => ProjectInstructionsLoadResult;
+}
+
+export type HeadlessExecTimingValue = string | number | boolean | null | readonly string[];
+
+export interface HeadlessExecTiming {
+  enabled: boolean;
+  mark: (phase: string, fields?: Record<string, HeadlessExecTimingValue>) => void;
+}
+
+export function createHeadlessExecTiming(options: {
+  enabled: boolean;
+  stderr?: Pick<NodeJS.WriteStream, "write">;
+  startTimeMs?: number;
+}): HeadlessExecTiming {
+  const startTimeMs = options.startTimeMs ?? Date.now();
+  const stderr = options.stderr ?? process.stderr;
+  let previousElapsedMs = 0;
+
+  return {
+    enabled: options.enabled,
+    mark: (phase, fields = {}) => {
+      if (!options.enabled) return;
+      const elapsedMs = Date.now() - startTimeMs;
+      const deltaMs = elapsedMs - previousElapsedMs;
+      previousElapsedMs = elapsedMs;
+      const formattedFields = Object.entries(fields)
+        .map(([key, value]) => {
+          const serialized = Array.isArray(value) || typeof value === "string"
+            ? JSON.stringify(value)
+            : String(value);
+          return `${key}=${serialized}`;
+        })
+        .join(" ");
+      writeLine(stderr, `[ubume exec timing] phase=${phase} elapsed_ms=${elapsedMs} delta_ms=${deltaMs}${formattedFields ? ` ${formattedFields}` : ""}`);
+    },
+  };
+}
+
+export const createHeadlessBenchmarkDiagnostics = createHeadlessExecTiming;
+
+const DEFAULT_DEPENDENCIES: HeadlessExecDependencies = {
+  resolveWorkspaceRoot,
+  resolveLayeredConfig,
+  resolveRuntimeConfig,
+  getBackendProvider,
+  loadProjectInstructions,
+};
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function writeLine(stream: Pick<NodeJS.WriteStream, "write">, line: string): void {
+  stream.write(`${line}\n`);
+}
+
+function formatDiagnosticText(value: string): string {
+  return sanitizeTerminalOutput(value)
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .trim();
+}
+
+function writeDiagnostic(stderr: Pick<NodeJS.WriteStream, "write">, kind: string, message: string): void {
+  const safeMessage = formatDiagnosticText(message);
+  if (!safeMessage) return;
+  writeLine(stderr, `[ubume exec] ${kind}: ${safeMessage.replace(/\n/g, "\n  ")}`);
+}
+
+function formatToolActivity(activity: RunToolActivity): string {
+  const summary = activity.summary?.trim();
+  const safeSummary = summary && isProcessTerminationNoise(summary) ? "" : summary;
+  return summary
+    ? `${activity.status}: ${activity.command}${safeSummary ? `\n${safeSummary}` : ""}`
+    : `${activity.status}: ${activity.command}`;
+}
+
+function isStructuredCodexEventLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return false;
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as { type?: unknown };
+    return typeof parsed.type === "string"
+      && /^(?:thread|turn|item)\./.test(parsed.type);
+  } catch {
+    return false;
+  }
+}
+
+function isProcessTerminationNoise(line: string): boolean {
+  return /^SUCCESS: The process with PID \d+ .* has been terminated\.$/.test(line.trim());
+}
+
+function shouldSuppressAssistantChunk(chunk: string): boolean {
+  const lines = chunk
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  return lines.length > 0
+    && lines.every((line) => isStructuredCodexEventLine(line) || isProcessTerminationNoise(line));
+}
+
+function formatRuntimeStartup(runtime: ResolvedRuntimeConfig, workspaceRoot: string, provider: BackendProvider): string {
+  return [
+    `workspace ${workspaceRoot}`,
+    `provider ${provider.label} (${provider.id})`,
+    `model ${runtime.model}`,
+    `mode ${runtime.mode}`,
+    `planMode ${runtime.planMode ? "enabled" : "disabled"}`,
+    `sandbox ${runtime.policy.sandboxMode}`,
+    `approval ${runtime.policy.approvalPolicy}`,
+    `network ${runtime.policy.networkAccess ? "enabled" : "disabled"}`,
+  ].join("; ");
+}
+
+// ─── Runner ───────────────────────────────────────────────────────────────────
+
+export async function runHeadlessExec(
+  options: HeadlessExecOptions,
+  io: HeadlessExecIo = { stdout: process.stdout, stderr: process.stderr },
+  dependencies: Partial<HeadlessExecDependencies> = {},
+): Promise<HeadlessExecResult> {
+  const deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+  const diagnostics = options.benchmarkDiagnostics;
+  const promptPolicy = options.promptPolicy ?? "raw";
+  diagnostics?.mark("run_headless_start");
+  const workspaceRoot = options.workspaceRoot ?? deps.resolveWorkspaceRoot();
+  diagnostics?.mark("workspace_resolved", { workspace_root: workspaceRoot });
+  const layeredConfig = deps.resolveLayeredConfig({
+    workspaceRoot,
+    launchArgs: options.launchArgs,
+  });
+  diagnostics?.mark("layered_config_loaded");
+  const runtimeConfig = mergeRuntimeConfig(layeredConfig.runtime, { planMode: false });
+  const runtime = deps.resolveRuntimeConfig(runtimeConfig);
+  diagnostics?.mark("runtime_config_resolved", {
+    effective_model: runtime.model,
+    effective_reasoning_effort: runtime.reasoningLevel,
+    prompt_policy: promptPolicy,
+  });
+
+  const projectInstructionsLoad = promptPolicy === "wrapped"
+    ? deps.loadProjectInstructions(workspaceRoot)
+    : ({ status: "missing" } as ProjectInstructionsLoadResult);
+  const projectInstructions = projectInstructionsLoad.status === "loaded"
+    ? projectInstructionsLoad.instructions
+    : null;
+  diagnostics?.mark("project_instructions_resolved", {
+    whether_project_instructions_loaded: projectInstructionsLoad.status === "loaded",
+    project_instructions_path: projectInstructions?.path ?? ("path" in projectInstructionsLoad ? projectInstructionsLoad.path : null),
+    project_instructions_character_count: projectInstructions?.content.length ?? 0,
+  });
+
+  const provider = deps.getBackendProvider(runtime.provider);
+  diagnostics?.mark("provider_created", {
+    provider_id: provider.id,
+    provider_label: provider.label,
+  });
+
+  writeDiagnostic(io.stderr, "startup", formatRuntimeStartup(runtime, workspaceRoot, provider));
+
+  if (layeredConfig.diagnostics.ignoredEntries.length > 0) {
+    writeDiagnostic(io.stderr, "config", `ignored ${layeredConfig.diagnostics.ignoredEntries.join("; ")}`);
+  }
+
+  if (projectInstructionsLoad.status === "error") {
+    writeDiagnostic(io.stderr, "config", `could not load project instructions at ${projectInstructionsLoad.path}: ${projectInstructionsLoad.message}`);
+  }
+
+  if (!provider.run) {
+    writeDiagnostic(io.stderr, "error", `${provider.label} is unavailable for headless execution.`);
+    return { exitCode: HEADLESS_EXEC_PROVIDER_UNAVAILABLE };
+  }
+
+  return await new Promise<HeadlessExecResult>((resolve) => {
+    let settled = false;
+    const settle = (exitCode: number) => {
+      if (settled) return;
+      settled = true;
+      resolve({ exitCode });
+    };
+
+    try {
+      let streamedAssistantChars = 0;
+      const toolActivityIds = new Set<string>();
+
+      provider.run!(
+        options.prompt,
+        { runtime, workspaceRoot, projectInstructions, promptPolicy },
+        {
+          onAssistantDelta: (chunk) => {
+            const safeChunk = sanitizeTerminalOutput(chunk, { preserveTabs: false, tabSize: 2 });
+            if (shouldSuppressAssistantChunk(safeChunk)) return;
+            if (!safeChunk) return;
+            streamedAssistantChars += safeChunk.length;
+            io.stdout.write(safeChunk);
+          },
+          onProgress: (update) => {
+            const safeText = formatDiagnosticText(update.text);
+            if (!safeText || isNoiseLine(safeText) || isProcessTerminationNoise(safeText)) return;
+            if (update.source === "tool" && toolActivityIds.has(update.id)) return;
+            writeDiagnostic(io.stderr, update.source, safeText);
+          },
+          onToolActivity: (activity) => {
+            toolActivityIds.add(activity.id);
+            writeDiagnostic(io.stderr, "tool", formatToolActivity(activity));
+          },
+          onFinalAnswerObserved: (response) => {
+            diagnostics?.mark("final_answer_observed", {
+              final_answer_character_count: response.length,
+            });
+          },
+          onResponse: (response) => {
+            const safeResponse = sanitizeTerminalOutput(response, { preserveTabs: false, tabSize: 2 });
+            if (streamedAssistantChars === 0 && safeResponse) {
+              io.stdout.write(safeResponse);
+            }
+            settle(0);
+          },
+          onError: (message, rawOutput) => {
+            const details = [message, rawOutput].filter((value) => value?.trim()).join("\n");
+            writeDiagnostic(io.stderr, "error", details || "Provider run failed.");
+            settle(HEADLESS_EXEC_RUN_FAILED);
+          },
+          benchmarkHooks: diagnostics?.enabled
+            ? {
+                onProviderPrepStart: () => diagnostics.mark("provider_prep_start"),
+                onProviderPrepComplete: () => diagnostics.mark("provider_prep_complete"),
+                onProviderPromptPrepared: ({ policy, characterCount }) => diagnostics.mark("provider_prompt_prepared", {
+                  prompt_policy: policy,
+                  prompt_character_count_before_wrapping: options.prompt.length,
+                  prompt_character_count_after_wrapping: characterCount,
+                }),
+                onCodexProcessSpawned: ({ executable, argv }) => diagnostics.mark("codex_process_spawned", {
+                  codex_argv_preview: [executable, ...argv].join(" "),
+                }),
+                onFirstStdout: (observed = true) => diagnostics.mark("first_stdout", { observed }),
+                onFirstStderr: (observed = true) => diagnostics.mark("first_stderr", { observed }),
+                onCodexProcessExit: (exitCode) => diagnostics.mark("codex_process_exit", {
+                  exit_code: exitCode,
+                }),
+                onCleanupStart: () => diagnostics.mark("cleanup_start"),
+                onCleanupComplete: ({ skipped }) => diagnostics.mark("cleanup_complete", { skipped }),
+              }
+            : undefined,
+        },
+      );
+    } catch (error) {
+      writeDiagnostic(io.stderr, "error", error instanceof Error ? error.message : String(error));
+      settle(HEADLESS_EXEC_RUN_FAILED);
+    }
+  });
+}