jeo-code 0.1.0 → 0.4.5

package/src/agent/state.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import * as os from "node:os";
 import { parseConfig } from "./config-schema";
+import { jeoEnv } from "../util/env";
 
 /** Persisted OAuth credential set (access + refresh + expiry) for a provider. */
 export interface StoredOAuth {
@@ -14,30 +15,45 @@ export interface StoredOAuth {
   projectId?: string;
 }
 
+export interface HookConfig {
+  enabled?: boolean;
+  hooks?: Array<{
+    event: "pre-tool" | "post-turn" | "post-implementation";
+    match?: { tool?: string };
+    run: string;
+    timeoutMs?: number;
+  }>;
+}
+
 export interface Config {
   providers: {
     anthropic?: string;
     openai?: string;
     gemini?: string;
+    antigravity?: string;
   };
   /**
-   * OAuth credentials (take precedence over API keys for the same provider).
-   * A bare string is a legacy/manually-pasted bearer with no refresh metadata;
-   * a {@link StoredOAuth} object carries refresh token + expiry for auto-refresh.
+   * OAuth credentials. `resolveCredential()` returns these before API keys so refresh
+   * metadata is not lost, but provider execution/status applies the GJC parity rule:
+   * an API key is broader and wins whenever both key + OAuth exist.
    */
   oauth?: {
     anthropic?: string | StoredOAuth;
     openai?: string | StoredOAuth;
     gemini?: string | StoredOAuth;
+    antigravity?: string | StoredOAuth;
   };
   /** Base URL for the local Ollama server (keyless). */
   ollamaBaseUrl?: string;
   /** Base URL override for OpenAI-compatible providers (LM Studio, vLLM, llama-cpp-server, ...). */
   openaiBaseUrl?: string;
   defaultModel: string;
+  theme?: string;
   thinkingLevel?: "minimal" | "low" | "medium" | "high" | "xhigh";
   /** Friendly model aliases, e.g. { fast: "ollama/qwen2.5:0.5b" }. Override built-ins. */
   modelAliases?: { [alias: string]: string };
+  /** Most-recently-selected models, newest first (MRU; head == defaultModel). */
+  recentModels?: string[];
   /**
    * Provider retry budgets (gjc parity). `requestMaxRetries` is the number of
    * retries (excluding the initial request) for a provider request; `maxDelayMs`
@@ -49,18 +65,57 @@ export interface Config {
     streamMaxRetries?: number;
     maxRetries?: number;
     maxDelayMs?: number;
+    /** Retries (excluding the initial request) specifically for 429 rate limits. */
+    rateLimitRetries?: number;
+    /** Minimum backoff (ms) for a 429 when the server sends no Retry-After. */
+    rateLimitMinDelayMs?: number;
+    /** HTTP statuses to treat as NON-retryable even when defaultRetryable would
+     *  retry them (e.g. pin 503 to fail fast instead of riding the backoff ladder). */
+    failFastStatuses?: number[];
+    /** Case-insensitive substrings; an error whose message matches any of these
+     *  fails fast (non-retryable) even when the chosen predicate would retry it. */
+    failFastPatterns?: string[];
   };
   /**
-   * Per-subagent-role overrides (gjc role-agent parity). Keyed by role id
-   * (executor / planner / architect / critic); each may pin a model and/or a
-   * tool-loop step budget.
+   * Per-subagent-role overrides (gjc role-agent parity), keyed by role id.
+   * Bundled ids (executor / planner / architect / critic) take model / maxSteps /
+   * thinking pins. A NON-bundled id that declares `title`, `description`, or
+   * `prompt` becomes a config-defined CUSTOM ROLE (system-driven registry —
+   * see rolesFromConfig). Custom roles are read-only unless `readOnly: false`.
    */
-  subagents?: { [roleId: string]: { model?: string; maxSteps?: number } };
+  subagents?: {
+    [roleId: string]: {
+      model?: string;
+      maxSteps?: number;
+      thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+      title?: string;
+      description?: string;
+      prompt?: string;
+      readOnly?: boolean;
+    };
+  };
   /**
    * Model role tiers (gjc `--smol`/`--slow`/`--plan` parity). Each falls back to
-   * `defaultModel`. Env `JOC_SMOL_MODEL`/`JOC_SLOW_MODEL`/`JOC_PLAN_MODEL` fill gaps.
+   * `defaultModel`. Env `JEO_SMOL_MODEL`/`JEO_SLOW_MODEL`/`JEO_PLAN_MODEL` fill gaps.
    */
   roles?: { smol?: string; slow?: string; plan?: string };
+  hooks?: HookConfig;
+}
+
+export interface WorkflowTopologyComponent {
+  id: string;
+  name: string;
+  description: string;
+  status: "active" | "deferred";
+  evidence?: string[];
+}
+
+export interface WorkflowTopologyState {
+  status: "pending" | "confirmed" | "legacy_missing";
+  confirmed_at?: string | null;
+  components: WorkflowTopologyComponent[];
+  deferrals?: Array<{ component_id: string; reason: string; confirmed_at: string }>;
+  last_targeted_component_id?: string | null;
 }
 
 export interface WorkflowState {
@@ -72,20 +127,45 @@ export interface WorkflowState {
   initial_idea?: string;
   current_ambiguity?: number;
   threshold?: number;
+  threshold_source?: string;
+  type?: "greenfield" | "brownfield";
   seed_path?: string;
+  topology?: WorkflowTopologyState;
+  codebase_context?: string;
+  language?: string;
   plan_path?: string;
   completed_tasks?: string[];
   pending_tasks?: string[];
+  /** team: the task the previous run failed on — surfaces a partial-edits
+   *  warning on resume (round-8). Cleared when the run resumes past it. */
+  failed_task?: string;
+  /** ralplan: persisted consensus-critic verdict ("okay" | "iterate" | "reject" |
+   *  "unverified") — `jeo approve` requires "okay" (round-11 real consensus). */
+  consensus?: string;
+  /** ralplan: the critic's justification (bounded excerpt) for auditability. */
+  consensus_detail?: string;
   approved?: boolean;
+  /** ultragoal terminal outcome. */
+  status?: string;
+  passed?: number;
+  total?: number;
+  /** ultragoal: whether the global verification suite was green (round-7 honest
+   *  contract — criteria are recorded, not individually claimed as passed). */
+  suite_green?: boolean;
 }
 
+/** The built-in default model when neither disk config nor JEO_DEFAULT_MODEL provides one.
+ *  Shared by envDefaultConfig (runtime) and readRawGlobalConfig (persistence base) so a
+ *  fresh-install saveConfigPatch never bakes a DIFFERENT default than the runtime resolves. */
+const DEFAULT_MODEL = "claude-sonnet-4-5";
+
 /**
  * Resolve the global config directory at call time (not import time) so that a
- * `JOC_CONFIG_DIR` override or a runtime `HOME` change is always honored.
- * `JOC_CONFIG_DIR` takes precedence; otherwise `~/.joc`.
+ * `JEO_CONFIG_DIR` override or a runtime `HOME` change is always honored.
+ * `JEO_CONFIG_DIR` takes precedence; otherwise `~/.jeo`.
  */
 function globalConfigDir(): string {
-  return process.env.JOC_CONFIG_DIR || path.join(os.homedir(), ".joc");
+  return jeoEnv("CONFIG_DIR") || path.join(os.homedir(), ".jeo");
 }
 function globalConfigPath(): string {
   return path.join(globalConfigDir(), "config.json");
@@ -99,20 +179,31 @@ function envOAuth(): NonNullable<Config["oauth"]> {
   };
 }
 
-/** Merge env-provided OAuth tokens / Ollama base over a config (env fills gaps only). */
+/** Merge env-provided credentials / base URLs over a config (env fills gaps only;
+ *  on-disk values always win). Previously the providers API-key map was NOT overlaid
+ *  when a config file existed, so a provider whose key lived only in the environment
+ *  (e.g. GEMINI_API_KEY) resolved to "no credential" — breaking provider/model
+ *  selection (including per-role subagent overrides) despite the key being present. */
 function withEnvOverlay(cfg: Config): Config {
   const envTok = envOAuth();
   const oauth = { ...envTok, ...(cfg.oauth ?? {}) };
+  // Disk wins when it is a real key; env fills missing/blank gaps. A hand-edited
+  // empty string should not mask a valid environment credential.
+  const providers: Config["providers"] = { ...(cfg.providers ?? {}) };
+  if (!providers.anthropic && process.env.ANTHROPIC_API_KEY) providers.anthropic = process.env.ANTHROPIC_API_KEY;
+  if (!providers.openai && process.env.OPENAI_API_KEY) providers.openai = process.env.OPENAI_API_KEY;
+  if (!providers.gemini && process.env.GEMINI_API_KEY) providers.gemini = process.env.GEMINI_API_KEY;
   return {
     ...cfg,
+    providers,
     oauth,
-    defaultModel: process.env.JOC_DEFAULT_MODEL || cfg.defaultModel,
+    defaultModel: jeoEnv("DEFAULT_MODEL") || cfg.defaultModel,
     ollamaBaseUrl: cfg.ollamaBaseUrl || process.env.OLLAMA_HOST || "http://localhost:11434",
     openaiBaseUrl: cfg.openaiBaseUrl || process.env.OPENAI_BASE_URL,
     roles: {
-      smol: cfg.roles?.smol || process.env.JOC_SMOL_MODEL,
-      slow: cfg.roles?.slow || process.env.JOC_SLOW_MODEL,
-      plan: cfg.roles?.plan || process.env.JOC_PLAN_MODEL,
+      smol: cfg.roles?.smol || jeoEnv("SMOL_MODEL"),
+      slow: cfg.roles?.slow || jeoEnv("SLOW_MODEL"),
+      plan: cfg.roles?.plan || jeoEnv("PLAN_MODEL"),
     },
   };
 }
@@ -124,50 +215,122 @@ function envDefaultConfig(): Config {
       openai: process.env.OPENAI_API_KEY,
       gemini: process.env.GEMINI_API_KEY,
     },
-    defaultModel: process.env.JOC_DEFAULT_MODEL || "claude-3-5-sonnet",
+    defaultModel: jeoEnv("DEFAULT_MODEL") || DEFAULT_MODEL,
     thinkingLevel: "medium",
   };
 }
 
-export async function readGlobalConfig(): Promise<Config> {
-  let data: string;
+/**
+ * Parsed-config read cache keyed by path and validated by stat (mtimeMs + size).
+ * `readGlobalConfig`/`readRawGlobalConfig` run on EVERY model call (resolveCall,
+ * credential resolution, per-turn config reads), so an uncached read paid a disk
+ * read + JSON.parse + zod validation per agent-loop step. The cache is bounded
+ * (≤8 paths — one per JEO_CONFIG_DIR seen) and invalidated by `saveGlobalConfig`;
+ * any external write changes mtime/size, so a stale entry is never served. Reads
+ * return a structuredClone so callers can never poison the cached object.
+ */
+type ParsedFile =
+  | { kind: "ok"; config: Config }
+  | { kind: "missing" }
+  | { kind: "bad-json"; warned: boolean }
+  | { kind: "invalid"; message: string; warned: boolean };
+const configReadCache = new Map<string, { mtimeMs: number; size: number; parsed: ParsedFile }>();
+const CONFIG_CACHE_CAP = 8;
+
+/** Drop all cached config reads (tests / explicit invalidation). */
+export function clearConfigReadCache(): void {
+  configReadCache.clear();
+}
+
+async function readParsedConfigFile(): Promise<ParsedFile> {
+  const p = globalConfigPath();
+  let st: { mtimeMs: number; size: number };
   try {
-    data = await fs.readFile(globalConfigPath(), "utf-8");
+    st = await fs.stat(p);
   } catch {
-    return withEnvOverlay(envDefaultConfig());
+    configReadCache.delete(p);
+    return { kind: "missing" };
   }
-
-  let raw: unknown;
+  const hit = configReadCache.get(p);
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit.parsed;
+  let parsed: ParsedFile;
   try {
-    raw = JSON.parse(data);
+    const raw = JSON.parse(await fs.readFile(p, "utf-8"));
+    const result = parseConfig(raw);
+    parsed = result.ok
+      ? { kind: "ok", config: result.config as Config }
+      : { kind: "invalid", message: result.message, warned: false };
   } catch {
-    process.stderr.write(`[joc] ${globalConfigPath()} is not valid JSON; using environment defaults.\n`);
-    return withEnvOverlay(envDefaultConfig());
+    parsed = { kind: "bad-json", warned: false };
+  }
+  if (configReadCache.size >= CONFIG_CACHE_CAP && !configReadCache.has(p)) {
+    const oldest = configReadCache.keys().next().value;
+    if (oldest !== undefined) configReadCache.delete(oldest);
   }
+  configReadCache.set(p, { mtimeMs: st.mtimeMs, size: st.size, parsed });
+  return parsed;
+}
 
-  const parsed = parseConfig(raw);
-  if (!parsed.ok) {
-    process.stderr.write(`[joc] ${globalConfigPath()} is invalid (${parsed.message}); using environment defaults.\n`);
+export async function readGlobalConfig(): Promise<Config> {
+  const parsed = await readParsedConfigFile();
+  if (parsed.kind === "bad-json" || parsed.kind === "invalid") {
+    // Warn once per file VERSION (mtime/size change resets the entry), not per read.
+    if (!parsed.warned) {
+      parsed.warned = true;
+      const detail = parsed.kind === "invalid" ? ` is invalid (${parsed.message})` : " is not valid JSON";
+      process.stderr.write(`[jeo] ${globalConfigPath()}${detail}; using environment defaults.\n`);
+    }
     return withEnvOverlay(envDefaultConfig());
   }
-  return withEnvOverlay(parsed.config as Config);
+  if (parsed.kind === "missing") return withEnvOverlay(envDefaultConfig());
+  return withEnvOverlay(structuredClone(parsed.config));
 }
 
 export async function saveGlobalConfig(config: Config): Promise<void> {
-  await fs.mkdir(globalConfigDir(), { recursive: true, mode: 0o700 });
-  await fs.writeFile(globalConfigPath(), JSON.stringify(config, null, 2), { encoding: "utf-8", mode: 0o600 });
-  await fs.chmod(globalConfigPath(), 0o600).catch(() => {}); // ensure mode even if file pre-existed
+  const dir = globalConfigDir();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const target = globalConfigPath();
+  const tmpPath = `${target}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await fs.writeFile(tmpPath, JSON.stringify(config, null, 2), { encoding: "utf-8", mode: 0o600 });
+    await fs.chmod(tmpPath, 0o600).catch(() => {});
+    await fs.rename(tmpPath, target);
+    configReadCache.delete(target); // the next read re-parses the fresh file
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
 }
 
-export function getLocalJocDir(cwd: string = process.cwd()): string {
-  return path.join(cwd, ".joc");
+/** Read the on-disk config WITHOUT the env overlay. Used as the base for
+ *  persistence so env-only values (OAuth bearer tokens, JEO_DEFAULT_MODEL,
+ *  JEO_*_MODEL role tiers, OLLAMA_HOST/OPENAI_BASE_URL) are never baked into
+ *  ~/.jeo/config.json by an unrelated `/agents`/`/roles`/`/model save`. */
+export async function readRawGlobalConfig(): Promise<Config> {
+  const clean: Config = { providers: {}, defaultModel: DEFAULT_MODEL, thinkingLevel: "medium" };
+  const parsed = await readParsedConfigFile();
+  return parsed.kind === "ok" ? structuredClone(parsed.config) : clean;
+}
+
+/** Merge a patch onto the RAW on-disk config and persist. The `build` callback
+ *  receives the raw config so partial updates (subagents/roles maps) are derived
+ *  from on-disk state, never from the env-overlaid runtime config. */
+export async function saveConfigPatch(build: (raw: Config) => Partial<Config>): Promise<Config> {
+  const raw = await readRawGlobalConfig();
+  const next = { ...raw, ...build(raw) };
+  await saveGlobalConfig(next);
+  return next;
+}
+
+export function getLocalJeoDir(cwd: string = process.cwd()): string {
+  return path.join(cwd, ".jeo");
 }
 
 export async function readWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<WorkflowState | null> {
-  const statePath = path.join(getLocalJocDir(cwd), "state", `${skill}-state.json`);
+  const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
   try {
     const data = await fs.readFile(statePath, "utf-8");
     return JSON.parse(data) as WorkflowState;
@@ -176,15 +339,49 @@ export async function readWorkflowState(
   }
 }
 
+/**
+ * Like {@link readWorkflowState} but distinguishes a missing file (→ null) from a
+ * corrupt/invalid one (→ throws). Security-sensitive callers (the MutationGuard)
+ * use this to fail CLOSED: a corrupt lock state must not be treated as "no lock".
+ */
+export async function readWorkflowStateStrict(
+  skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
+  cwd: string = process.cwd()
+): Promise<WorkflowState | null> {
+  const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
+  let data: string;
+  try {
+    data = await fs.readFile(statePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    return JSON.parse(data) as WorkflowState;
+  } catch {
+    throw new Error(`workflow state ${statePath} is corrupt (invalid JSON)`);
+  }
+}
+
 export async function writeWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   state: WorkflowState,
   cwd: string = process.cwd()
 ): Promise<string> {
-  const stateDir = path.join(getLocalJocDir(cwd), "state");
+  const stateDir = path.join(getLocalJeoDir(cwd), "state");
   await fs.mkdir(stateDir, { recursive: true });
   const statePath = path.join(stateDir, `${skill}-state.json`);
-  await fs.writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+  // Atomic temp+rename (zeroclaw crash-durability): workflow state is rewritten
+  // repeatedly mid-workflow, and the mutation guard fails CLOSED on corrupt JSON —
+  // a torn write would otherwise wedge the agent into a permanent mutation block.
+  const tmpPath = `${statePath}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await fs.writeFile(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+    await fs.rename(tmpPath, statePath);
+  } catch (err) {
+    await fs.unlink(tmpPath).catch(() => {});
+    throw err;
+  }
   return statePath;
 }
 
@@ -192,8 +389,58 @@ export async function clearWorkflowState(
   skill: "deep-interview" | "ralplan" | "team" | "ultragoal",
   cwd: string = process.cwd()
 ): Promise<void> {
-  const statePath = path.join(getLocalJocDir(cwd), "state", `${skill}-state.json`);
+  const statePath = path.join(getLocalJeoDir(cwd), "state", `${skill}-state.json`);
   try {
     await fs.unlink(statePath);
   } catch {}
 }
+
+/**
+ * Cross-process run lock for a workflow engine (round-8, architect ref
+ * 7-Round7Workflow): two concurrent `jeo team` processes would read-modify-write
+ * team-state.json last-writer-wins — tasks executed twice, completions lost.
+ * O_EXCL lockfile carrying the holder's pid; a DEAD holder's stale lock is taken
+ * over once, a LIVE holder refuses with an actionable error. Returns a release fn.
+ */
+export async function acquireWorkflowRunLock(
+  skill: "team" | "ultragoal",
+  cwd: string = process.cwd(),
+): Promise<() => Promise<void>> {
+  const stateDir = path.join(getLocalJeoDir(cwd), "state");
+  await fs.mkdir(stateDir, { recursive: true });
+  const lockPath = path.join(stateDir, `${skill}.lock`);
+  const payload = JSON.stringify({ pid: process.pid, at: Date.now() });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      await fs.writeFile(lockPath, payload, { flag: "wx" });
+      return async () => {
+        await fs.unlink(lockPath).catch(() => {});
+      };
+    } catch {
+      let holder: { pid?: number } = {};
+      try {
+        holder = JSON.parse(await fs.readFile(lockPath, "utf-8")) as { pid?: number };
+      } catch { /* unreadable/torn lock → treat as stale */ }
+      const alive = typeof holder.pid === "number" && holder.pid > 0 && (() => {
+        try {
+          process.kill(holder.pid!, 0);
+          return true;
+        } catch {
+          return false;
+        }
+      })();
+      if (alive) {
+        throw new Error(
+          `another 'jeo ${skill}' run (pid ${holder.pid}) holds ${lockPath} — wait for it to finish, or delete the lock file if that process is gone.`,
+        );
+      }
+      await fs.unlink(lockPath).catch(() => {}); // stale (dead/unreadable) → take over once
+    }
+  }
+  throw new Error(`could not acquire ${lockPath} even after stale-lock takeover.`);
+}
+
+/** Returns true if the agent is running in development mode (enables self-improvement). */
+export function isDevMode(): boolean {
+  return jeoEnv("DEV_MODE") === "1" || process.env.NODE_ENV === "development";
+}