openagentflow 0.1.0

package/adapters/langgraph/templates.js

@@ -0,0 +1,502 @@
+/**
+ * OpenAgentFlow — LangGraph Python Templates
+ *
+ * This module contains the reusable Python templates and runtime helper stubs
+ * used by the LangGraph adapter. It has no knowledge of the OpenAgentFlow compiler,
+ * IR parsing, or JavaScript implementation.
+ */
+
+import { generateDemoHelperTemplate } from './demo_template.js';
+
+/**
+ * Generate the Python file header comment block.
+ * @param {object} params
+ * @param {string} params.workflowName
+ * @param {string} params.version
+ * @returns {string}
+ */
+export function generateHeaderTemplate({ workflowName, version }) {
+  return [
+    `"""`,
+    `OpenAgentFlow — Generated LangGraph Workflow`,
+    ``,
+    `Workflow: ${workflowName}`,
+    `Generated by: OpenAgentFlow Compiler v${version}`,
+    ``,
+    `This file was auto-generated from an .oaf workflow definition.`,
+    `Do not edit manually — regenerate from the source .oaf file.`,
+    `"""`,
+    ``,
+  ].join('\n');
+}
+
+/**
+ * Generate Python imports block.
+ * @param {object} params
+ * @param {string[]} params.typingImports - Array of typing symbols (e.g. ['Dict', 'List', 'Optional', 'TypedDict'])
+ * @param {boolean} params.needsLlmProviders - Whether to include provider import checks
+ * @returns {string}
+ */
+export function generateImportsTemplate({ typingImports, needsLlmProviders, needsOperator }) {
+  const lines = [
+    `import os`,
+    `import sys`,
+    `import json`,
+  ];
+
+  if (needsOperator) {
+    lines.push(`import operator`);
+  }
+
+  lines.push(`from typing import ${typingImports.sort().join(', ')}`);
+  lines.push(``);
+  lines.push(`from langgraph.graph import StateGraph, END`);
+
+  if (needsLlmProviders) {
+    lines.push(``);
+    lines.push(`# ─── Environment Variable Hierarchy ──────────────────────────────────────────`);
+    lines.push(`def _load_env_hierarchy():`);
+    lines.push(`    """Load environment variables from local .env and ~/.oaf/.env if not already set."""`);
+    lines.push(`    def parse_env_file(path):`);
+    lines.push(`        if not os.path.exists(path):`);
+    lines.push(`            return {}`);
+    lines.push(`        res = {}`);
+    lines.push(`        try:`);
+    lines.push(`            with open(path, "r", encoding="utf-8") as f:`);
+    lines.push(`                for line in f:`);
+    lines.push(`                    line = line.strip()`);
+    lines.push(`                    if not line or line.startswith("#") or "=" not in line:`);
+    lines.push(`                        continue`);
+    lines.push(`                    k, v = line.split("=", 1)`);
+    lines.push(`                    k, v = k.strip(), v.strip()`);
+    lines.push(`                    if (v.startswith('"') and v.endswith('"')) or (v.startswith("'") and v.endswith("'")):`);
+    lines.push(`                        v = v[1:-1]`);
+    lines.push(`                    res[k] = v`);
+    lines.push(`        except Exception:`);
+    lines.push(`            pass`);
+    lines.push(`        return res`);
+    lines.push(``);
+    lines.push(`    local_path = os.path.join(os.getcwd(), ".env")`);
+    lines.push(`    global_path = os.path.join(os.path.expanduser("~"), ".oaf", ".env")`);
+    lines.push(``);
+    lines.push(`    local_env = parse_env_file(local_path)`);
+    lines.push(`    global_env = parse_env_file(global_path)`);
+    lines.push(``);
+    lines.push(`    for k, v in local_env.items():`);
+    lines.push(`        if k not in os.environ:`);
+    lines.push(`            os.environ[k] = v`);
+    lines.push(`    for k, v in global_env.items():`);
+    lines.push(`        if k not in os.environ:`);
+    lines.push(`            os.environ[k] = v`);
+    lines.push(``);
+    lines.push(`_load_env_hierarchy()`);
+    lines.push(``);
+    lines.push(`# LLM providers — Gemini, OpenAI, Anthropic`);
+    lines.push(`_LLM_PROVIDER = "demo" if os.environ.get("OAF_DEMO") == "1" else None`);
+    lines.push(`if os.environ.get("OAF_DEMO") != "1":`);
+    lines.push(`    try:`);
+    lines.push(`        from langchain_google_genai import ChatGoogleGenerativeAI`);
+    lines.push(`        if os.environ.get("GOOGLE_API_KEY"):`);
+    lines.push(`            _LLM_PROVIDER = "gemini"`);
+    lines.push(`    except ImportError:`);
+    lines.push(`        pass`);
+    lines.push(``);
+    lines.push(`    try:`);
+    lines.push(`        from langchain_openai import ChatOpenAI`);
+    lines.push(`        if os.environ.get("OPENAI_API_KEY") and _LLM_PROVIDER is None:`);
+    lines.push(`            _LLM_PROVIDER = "openai"`);
+    lines.push(`    except ImportError:`);
+    lines.push(`        pass`);
+    lines.push(``);
+    lines.push(`    try:`);
+    lines.push(`        from langchain_anthropic import ChatAnthropic`);
+    lines.push(`        if os.environ.get("ANTHROPIC_API_KEY") and _LLM_PROVIDER is None:`);
+    lines.push(`            _LLM_PROVIDER = "anthropic"`);
+    lines.push(`    except ImportError:`);
+    lines.push(`        pass`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Generate the WorkflowState TypedDict definition.
+ * @param {object} params
+ * @param {Array<{ name: string, pyType: string }>} params.fields
+ * @returns {string}
+ */
+export function generateStateClassTemplate({ fields }) {
+  const lines = [
+    `# ─── State Schema ───────────────────────────────────────────────────────────`,
+    ``,
+    `class WorkflowState(TypedDict, total=False):`,
+  ];
+
+  if (!fields || fields.length === 0) {
+    lines.push(`    pass`);
+  } else {
+    for (const field of fields) {
+      const comment = field.required ? `  # @required` : '';
+      const baseType = `Optional[${field.pyType}]`;
+      const typeStr = field.reducer ? `Annotated[${baseType}, operator.add]` : baseType;
+      lines.push(`    ${field.name}: ${typeStr}${comment}`);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Generate the runtime LLM helper (`get_llm`).
+ * @param {object} params
+ * @param {string|null} params.defaultModel
+ * @param {number} params.defaultTemperature
+ * @returns {string}
+ */
+export function generateLlmHelperTemplate({ defaultModel, defaultTemperature }) {
+  const defaultModelArg = defaultModel != null ? `"${defaultModel}"` : `None`;
+  const lines = [
+    generateDemoHelperTemplate(),
+    `# ─── LLM Helper ─────────────────────────────────────────────────────────────`,
+    ``,
+    `def get_llm(model: Optional[str] = ${defaultModelArg}, temperature: float = ${defaultTemperature}, provider: Optional[str] = None):`,
+    `    """Get the LLM instance. Uses provided model directly; falls back to OAF_DEFAULT_MODEL or raises error."""`,
+    `    target_model = model if model else os.environ.get("OAF_DEFAULT_MODEL")`,
+    `    override_model = os.environ.get("OAF_OVERRIDE_MODEL")`,
+    `    if override_model:`,
+    `        target_model = override_model`,
+    `        provider = None`,
+    ``,
+    `    if not target_model:`,
+    `        raise RuntimeError(`,
+    `            "No model specified and no default model configured. "`,
+    `            "Please specify a 'model' property in your .oaf agent definition or set the OAF_DEFAULT_MODEL environment variable."`,
+    `        )`,
+    ``,
+    `    target_provider = provider`,
+    `    if not target_provider and target_model:`,
+    `        if target_model.startswith("claude-"):`,
+    `            target_provider = "anthropic"`,
+    `        elif target_model.startswith("gpt-") or target_model.startswith("o1") or target_model.startswith("o3"):`,
+    `            target_provider = "openai"`,
+    `        elif target_model.startswith("gemini-") or target_model.startswith("gemma-"):`,
+    `            target_provider = "gemini"`,
+    `    if not target_provider:`,
+    `        target_provider = _LLM_PROVIDER`,
+    ``,
+    `    # --- DEMO HOOK (Cleanly removable) ---`,
+    `    _demo_inst = _maybe_get_demo_llm(target_model, temperature, target_provider)`,
+    `    if _demo_inst is not None:`,
+    `        return _demo_inst`,
+    `    # -------------------------------------`,
+    ``,
+    `    if target_provider == "gemini":`,
+    `        try:`,
+    `            _cls = globals().get("ChatGoogleGenerativeAI")`,
+    `            if _cls is None:`,
+    `                from langchain_google_genai import ChatGoogleGenerativeAI as _cls`,
+    `            inst = _cls(model=target_model, temperature=temperature)`,
+    `            inst._oaf_provider = "gemini"`,
+    `            return inst`,
+    `        except ImportError:`,
+    `            raise RuntimeError("Missing package: pip install langchain-google-genai")`,
+    `    elif target_provider == "openai":`,
+    `        try:`,
+    `            _cls = globals().get("ChatOpenAI")`,
+    `            if _cls is None:`,
+    `                from langchain_openai import ChatOpenAI as _cls`,
+    `            inst = _cls(model=target_model, temperature=temperature)`,
+    `            inst._oaf_provider = "openai"`,
+    `            return inst`,
+    `        except ImportError:`,
+    `            raise RuntimeError("Missing package: pip install langchain-openai")`,
+    `    elif target_provider == "anthropic":`,
+    `        try:`,
+    `            _cls = globals().get("ChatAnthropic")`,
+    `            if _cls is None:`,
+    `                from langchain_anthropic import ChatAnthropic as _cls`,
+    `            inst = _cls(model=target_model, temperature=temperature)`,
+    `            inst._oaf_provider = "anthropic"`,
+    `            return inst`,
+    `        except ImportError:`,
+    `            raise RuntimeError("Missing package: pip install langchain-anthropic")`,
+    `    else:`,
+    `        raise RuntimeError(`,
+    `            "No LLM provider available or configured. Set GOOGLE_API_KEY (Gemini), OPENAI_API_KEY (OpenAI), or ANTHROPIC_API_KEY (Anthropic)."`,
+    `        )`,
+    ``,
+    `def _parse_llm_output(raw_content, outputs):`,
+    `    """Cleanly parse LLM content (string or list of thinking/text blocks) into state updates."""`,
+    `    if isinstance(raw_content, list):`,
+    `        text_parts = []`,
+    `        for block in raw_content:`,
+    `            if isinstance(block, dict):`,
+    `                if block.get("type") == "text" or "text" in block:`,
+    `                    text_parts.append(str(block.get("text", "")))`,
+    `            elif isinstance(block, str):`,
+    `                text_parts.append(block)`,
+    `        result_text = "\\n".join(text_parts).strip()`,
+    `    else:`,
+    `        result_text = str(raw_content).strip()`,
+    ``,
+    `    clean_text = result_text`,
+    `    if clean_text.startswith("\`\`\`"):`,
+    `        lines = clean_text.splitlines()`,
+    `        if lines and lines[0].startswith("\`\`\`"):`,
+    `            lines = lines[1:]`,
+    `        if lines and lines[-1].startswith("\`\`\`"):`,
+    `            lines = lines[:-1]`,
+    `        clean_text = "\\n".join(lines).strip()`,
+    ``,
+    `    if len(outputs) == 1:`,
+    `        out_key = outputs[0]`,
+    `        try:`,
+    `            parsed = json.loads(clean_text)`,
+    `            if isinstance(parsed, dict) and out_key in parsed:`,
+    `                return {out_key: parsed[out_key]}`,
+    `        except Exception:`,
+    `            pass`,
+    `        return {out_key: result_text}`,
+    `    elif len(outputs) > 1:`,
+    `        target_text = clean_text`,
+    `        if not (target_text.startswith("{") and target_text.endswith("}")):`,
+    `            start_idx = target_text.find("{")`,
+    `            end_idx = target_text.rfind("}")`,
+    `            if start_idx != -1 and end_idx != -1 and end_idx > start_idx:`,
+    `                target_text = target_text[start_idx:end_idx + 1]`,
+    `        try:`,
+    `            parsed = json.loads(target_text)`,
+    `            if isinstance(parsed, dict):`,
+    `                updates = {}`,
+    `                for out_key in outputs:`,
+    `                    if out_key in parsed:`,
+    `                        updates[out_key] = parsed[out_key]`,
+    `                if updates:`,
+    `                    return updates`,
+    `        except Exception:`,
+    `            pass`,
+    `        import re`,
+    `        updates = {}`,
+    `        for out_key in outputs:`,
+    `            pattern = re.compile("""(?:^|\\n)[ \\t]*[-*]?[ \\t]*(?:["'])?""" + re.escape(out_key) + """(?:["'])?[ \\t]*[:=][ \\t]*(.+)""", re.IGNORECASE)`,
+    `            match = pattern.search(clean_text)`,
+    `            if match:`,
+    `                val_str = match.group(1).strip()`,
+    `                try:`,
+    `                    updates[out_key] = json.loads(val_str)`,
+    `                except Exception:`,
+    `                    if val_str.isdigit() or (val_str.startswith("-") and val_str[1:].isdigit()):`,
+    `                        updates[out_key] = int(val_str)`,
+    `                    elif val_str.lower() in ("true", "false"):`,
+    `                        updates[out_key] = (val_str.lower() == "true")`,
+    `                    else:`,
+    `                        updates[out_key] = val_str`,
+    `        if updates:`,
+    `            return updates`,
+    `        return {outputs[0]: result_text}`,
+    `    else:`,
+    `        return {}`,
+    ``,
+  ];
+  return lines.join('\n');
+}
+
+/**
+ * Generate a single Agent node function.
+ * @param {object} params
+ * @param {string} params.fnName - Python function name (snake_case)
+ * @param {string} params.id - Agent ID
+ * @param {string|null} params.model - Model string
+ * @param {number} params.temperature - Numeric temperature
+ * @param {string|null} params.provider - Provider ('gemini'|'openai'|null)
+ * @param {string} params.escapedInstructions - Triple-quote escaped instructions
+ * @param {string[]} params.inputs - Array of input variable names
+ * @param {string[]} params.outputs - Array of output variable names
+ * @returns {string}
+ */
+export function generateAgentNodeTemplate({
+  fnName,
+  id,
+  model,
+  temperature,
+  provider,
+  escapedInstructions,
+  inputs,
+  outputs,
+}) {
+  const modelArg = model != null ? `"${model}"` : `None`;
+  const providerArg = provider ? `"${provider}"` : `None`;
+  const formatPrompt = outputs.length > 1
+    ? `\\n\\nIMPORTANT: You must respond ONLY with a valid JSON object containing exactly these fields: ${outputs.join(', ')}. Do not include any other text, markdown, or commentary outside the JSON object.`
+    : '';
+
+  const lines = [
+    `def ${fnName}(state: WorkflowState) -> WorkflowState:`,
+    `    """Agent: ${id}"""`,
+    `    llm = get_llm(model=${modelArg}, temperature=${temperature}, provider=${providerArg})`,
+    `    print(f'[${id}] Running agent (model=${modelArg}, provider={getattr(llm, "_oaf_provider", "unknown")})')`,
+    ``,
+    `    system_prompt = """${escapedInstructions}${formatPrompt}"""`,
+    ``,
+  ];
+
+  if (inputs && inputs.length > 0) {
+    lines.push(`    # Collect input from state`);
+    lines.push(`    user_parts = []`);
+    for (const input of inputs) {
+      lines.push(`    if state.get("${input}") is not None:`);
+      lines.push(`        user_parts.append(f"${input}: {state['${input}']}")`);
+    }
+    lines.push(`    user_message = "\\n".join(user_parts) if user_parts else "No input provided."`);
+  } else {
+    lines.push(`    user_message = json.dumps({k: v for k, v in state.items() if v is not None})`);
+  }
+
+  lines.push(``);
+  lines.push(`    messages = [`);
+  lines.push(`        {"role": "system", "content": system_prompt},`);
+  lines.push(`        {"role": "user", "content": user_message},`);
+  lines.push(`    ]`);
+  lines.push(``);
+  lines.push(`    response = llm.invoke(messages)`);
+  lines.push(`    return _parse_llm_output(response.content, ${JSON.stringify(outputs)})`);
+  lines.push(``);
+  lines.push(``);
+  return lines.join('\n');
+}
+
+/**
+ * Generate the build_graph() function.
+ * @param {object} params
+ * @param {Array<{ id: string, fnName: string }>} params.nodes
+ * @param {string} params.entrypoint
+ * @param {Array<{ source: string, target: string }>} params.edges
+ * @param {string[]} params.terminals
+ * @returns {string}
+ */
+export function generateGraphBuilderTemplate({ nodes, entrypoint, edges, terminals }) {
+  const lines = [
+    `# ─── Graph Construction ──────────────────────────────────────────────────────`,
+    ``,
+    `def build_graph() -> StateGraph:`,
+    `    """Build and compile the LangGraph workflow."""`,
+    `    graph = StateGraph(WorkflowState)`,
+    ``,
+    `    # Register agent nodes`,
+  ];
+
+  for (const node of nodes) {
+    lines.push(`    graph.add_node("${node.id}", ${node.fnName})`);
+  }
+  lines.push(``);
+
+  lines.push(`    # Set entry point`);
+  lines.push(`    graph.set_entry_point("${entrypoint}")`);
+  lines.push(``);
+
+  if (edges && edges.length > 0) {
+    lines.push(`    # Add edges between agents`);
+    for (const edge of edges) {
+      lines.push(`    graph.add_edge("${edge.source}", "${edge.target}")`);
+    }
+    lines.push(``);
+  }
+
+  lines.push(`    # Connect terminal nodes to END`);
+  for (const terminal of terminals) {
+    lines.push(`    graph.add_edge("${terminal}", END)`);
+  }
+  lines.push(``);
+  lines.push(`    return graph.compile()`);
+  lines.push(``);
+  return lines.join('\n');
+}
+
+/**
+ * Generate the __main__ execution block.
+ * @param {object} params
+ * @param {string} params.workflowName
+ * @param {Array<{ name: string, defaultVal: string }>} params.initialStateFields
+ * @returns {string}
+ */
+export function generateMainTemplate({ workflowName, initialStateFields, requiredFields = [] }) {
+  const lines = [
+    `# ─── Execution ──────────────────────────────────────────────────────────────`,
+    ``,
+    `if __name__ == "__main__":`,
+    `    if hasattr(sys.stdout, 'reconfigure'):`,
+    `        sys.stdout.reconfigure(encoding='utf-8')`,
+    `    # Ensure at least one API key is set`,
+    `    if not _LLM_PROVIDER:`,
+    `        print("Error: No LLM provider configured.")`,
+    `        print("  Set GOOGLE_API_KEY (Gemini, preferred) or OPENAI_API_KEY (OpenAI).")`,
+    `        print("  Example: export GOOGLE_API_KEY='your-key-here'")`,
+    `        exit(1)`,
+    ``,
+    `    print(f"Default fallback provider: {_LLM_PROVIDER}")`,
+    `    app = build_graph()`,
+    ``,
+    `    # Initial state — populate input fields before running`,
+    `    initial_state: WorkflowState = {`,
+  ];
+
+  for (const field of initialStateFields) {
+    lines.push(`        "${field.name}": ${field.defaultVal},`);
+  }
+
+  lines.push(`    }`);
+  lines.push(``);
+  lines.push(`    # Override initial_state from --input / -i file or OAF_INPUT_FILE if provided at runtime`);
+  lines.push(`    input_file = os.environ.get("OAF_INPUT_FILE")`);
+  lines.push(`    args = sys.argv[1:]`);
+  lines.push(`    for idx in range(len(args)):`);
+  lines.push(`        if args[idx] in ("--input", "-i") and idx + 1 < len(args):`);
+  lines.push(`            input_file = args[idx + 1]`);
+  lines.push(`            break`);
+  lines.push(`        elif args[idx].startswith("--input="):`);
+  lines.push(`            input_file = args[idx].split("=")[1]`);
+  lines.push(`            break`);
+  lines.push(`        elif args[idx].startswith("-i="):`);
+  lines.push(`            input_file = args[idx].split("=")[1]`);
+  lines.push(`            break`);
+  lines.push(``);
+  lines.push(`    if input_file:`);
+  lines.push(`        try:`);
+  lines.push(`            with open(input_file, "r", encoding="utf-8") as f:`);
+  lines.push(`                runtime_input = json.load(f)`);
+  lines.push(`                if isinstance(runtime_input, dict):`);
+  lines.push(`                    initial_state.update(runtime_input)`);
+  lines.push(`        except Exception as err:`);
+  lines.push(`            print(f"Error reading input file '{input_file}': {err}", file=sys.stderr)`);
+  lines.push(`            sys.exit(1)`);
+  lines.push(``);
+
+  if (requiredFields && requiredFields.length > 0) {
+    lines.push(`    # Validate required state variables`);
+    lines.push(`    missing_required = [`);
+    lines.push(`        f for f in ${JSON.stringify(requiredFields)}`);
+    lines.push(`        if initial_state.get(f) is None or (isinstance(initial_state.get(f), str) and initial_state.get(f) == "")`);
+    lines.push(`    ]`);
+    lines.push(`    if missing_required:`);
+    lines.push(`        print(f"Error: Missing required state variables: {', '.join(missing_required)}", file=sys.stderr)`);
+    lines.push(`        sys.exit(1)`);
+    lines.push(``);
+  }
+
+  lines.push(`    print(f"Running workflow: ${workflowName}")`);
+  lines.push(`    print(f"{'-' * 50}")`);
+  lines.push(``);
+  lines.push(`    result = app.invoke(initial_state)`);
+  lines.push(``);
+  lines.push(`    print(f"{'-' * 50}")`);
+  lines.push(`    print("Workflow completed. Final state:")`);
+  lines.push(`    # --- DEMO HOOK (Cleanly removable) ---`);
+  lines.push(`    _final_state = _format_demo_state(result, initial_state) if "_format_demo_state" in globals() else result`);
+  lines.push(`    print(json.dumps(_final_state, indent=2, default=str))`);
+  lines.push(`    # -------------------------------------`);
+  lines.push(``);
+
+  return lines.join('\n');
+}

package/cli/env.js

@@ -0,0 +1,193 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, statSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import os from 'os';
+import readline from 'readline';
+
+const colors = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  cyan:    '\x1b[36m',
+  dim:     '\x1b[2m',
+};
+
+/**
+ * Parse raw .env file content into a key-value object.
+ * Supports comments, single/double quotes, and basic trimming.
+ */
+export function parseDotEnv(content) {
+  const result = {};
+  const lines = content.split(/\r?\n/);
+
+  for (let line of lines) {
+    line = line.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+
+    const eqIndex = line.indexOf('=');
+    if (eqIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIndex).trim();
+    let val = line.slice(eqIndex + 1).trim();
+
+    if (val.startsWith('"') && val.endsWith('"') && val.length >= 2) {
+      val = val.slice(1, -1).replace(/\\n/g, '\n').replace(/\\"/g, '"');
+    } else if (val.startsWith("'") && val.endsWith("'") && val.length >= 2) {
+      val = val.slice(1, -1);
+    } else {
+      // Remove trailing comments for unquoted values
+      const commentIndex = val.indexOf(' #');
+      if (commentIndex !== -1) {
+        val = val.slice(0, commentIndex).trim();
+      }
+    }
+
+    if (key) {
+      result[key] = val;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve environment variables across the 4-tier hierarchy:
+ * 1. Inline CLI overrides & System Environment Variables (already in process.env)
+ * 2. Local Project .env (sitting next to targetFilePath or process.cwd())
+ * 3. System Environment Variables (merged with #1 in Node process.env)
+ * 4. Global OAF Store (~/.oaf/.env)
+ */
+export function resolveEnvHierarchy(targetFilePath = null) {
+  const initialEnvKeys = new Set(Object.keys(process.env));
+  const resolvedSources = new Map();
+
+  for (const key of initialEnvKeys) {
+    resolvedSources.set(key, 'inline_or_system');
+  }
+
+  if (process.env.OAF_IGNORE_DOTENV) {
+    return { sources: resolvedSources };
+  }
+
+  const globalEnvPath = join(os.homedir(), '.oaf', '.env');
+  let globalEnv = {};
+  if (existsSync(globalEnvPath)) {
+    try {
+      globalEnv = parseDotEnv(readFileSync(globalEnvPath, 'utf-8'));
+    } catch (err) {}
+  }
+
+  let localEnvPath = null;
+  if (targetFilePath && existsSync(targetFilePath)) {
+    const absTarget = resolve(targetFilePath);
+    try {
+      const dir = statSync(absTarget).isDirectory() ? absTarget : dirname(absTarget);
+      localEnvPath = join(dir, '.env');
+    } catch (err) {
+      localEnvPath = join(process.cwd(), '.env');
+    }
+  } else {
+    localEnvPath = join(process.cwd(), '.env');
+  }
+
+  let localEnv = {};
+  if (localEnvPath && existsSync(localEnvPath)) {
+    try {
+      localEnv = parseDotEnv(readFileSync(localEnvPath, 'utf-8'));
+    } catch (err) {}
+  }
+
+  // Tier 2: Local Project .env (overrides Tier 4 when not in process.env already)
+  for (const [key, val] of Object.entries(localEnv)) {
+    if (!initialEnvKeys.has(key)) {
+      process.env[key] = val;
+      resolvedSources.set(key, 'local_env');
+    }
+  }
+
+  // Tier 4: Global OAF Store (~/.oaf/.env)
+  for (const [key, val] of Object.entries(globalEnv)) {
+    if (!initialEnvKeys.has(key) && !localEnv.hasOwnProperty(key)) {
+      process.env[key] = val;
+      resolvedSources.set(key, 'global_env');
+    }
+  }
+
+  return {
+    sources: resolvedSources,
+    globalEnvPath,
+    localEnvPath: (localEnvPath && existsSync(localEnvPath)) ? localEnvPath : null,
+  };
+}
+
+/**
+ * Interactive setup for `oaf auth`.
+ * Prompts for API keys and writes them to ~/.oaf/.env with 600 permissions.
+ */
+export async function setupAuth() {
+  const oafDir = join(os.homedir(), '.oaf');
+  const envPath = join(oafDir, '.env');
+
+  if (!existsSync(oafDir)) {
+    mkdirSync(oafDir, { recursive: true, mode: 0o700 });
+    try { chmodSync(oafDir, 0o700); } catch (e) {}
+  }
+
+  let existing = {};
+  if (existsSync(envPath)) {
+    try {
+      existing = parseDotEnv(readFileSync(envPath, 'utf-8'));
+    } catch (err) {}
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const ask = (query) => new Promise((resolvePrompt) => rl.question(query, resolvePrompt));
+
+  console.log(`${colors.bold}OpenAgentFlow Authentication Setup${colors.reset}\n`);
+
+  try {
+    const openaiKey = await ask(`? Enter your OpenAI API Key (leave blank to skip): `);
+    const anthropicKey = await ask(`? Enter your Anthropic API Key (leave blank to skip): `);
+    const geminiKey = await ask(`? Enter your Google Gemini API Key (leave blank to skip): `);
+
+    rl.close();
+
+    const newEnv = { ...existing };
+    if (openaiKey !== undefined && openaiKey.trim() !== '') newEnv.OPENAI_API_KEY = openaiKey.trim();
+    if (anthropicKey !== undefined && anthropicKey.trim() !== '') newEnv.ANTHROPIC_API_KEY = anthropicKey.trim();
+    if (geminiKey !== undefined && geminiKey.trim() !== '') newEnv.GOOGLE_API_KEY = geminiKey.trim();
+
+    const lines = [
+      `# OpenAgentFlow Global Configuration (~/.oaf/.env)`,
+      `# File permissions: 600 (owner read/write only)`,
+    ];
+
+    if (newEnv.OPENAI_API_KEY) lines.push(`OPENAI_API_KEY=${newEnv.OPENAI_API_KEY}`);
+    if (newEnv.ANTHROPIC_API_KEY) lines.push(`ANTHROPIC_API_KEY=${newEnv.ANTHROPIC_API_KEY}`);
+    if (newEnv.GOOGLE_API_KEY) lines.push(`GOOGLE_API_KEY=${newEnv.GOOGLE_API_KEY}`);
+
+    for (const [k, v] of Object.entries(newEnv)) {
+      if (k !== 'OPENAI_API_KEY' && k !== 'ANTHROPIC_API_KEY' && k !== 'GOOGLE_API_KEY') {
+        lines.push(`${k}=${v}`);
+      }
+    }
+
+    writeFileSync(envPath, lines.join('\n') + '\n', { mode: 0o600 });
+    try { chmodSync(envPath, 0o600); } catch (e) {}
+
+    console.log(`\n${colors.green}✔ Saved to ~/.oaf/.env${colors.reset}`);
+  } catch (err) {
+    rl.close();
+    console.error(`\n${colors.red}✗ Authentication setup failed:${colors.reset} ${err.message}`);
+    process.exit(1);
+  }
+}