contextos-mcp 0.4.0

package/dist/core/types.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Shared type definitions for swarm-code.
+ */
+/** Token usage reported by the agent (when available). */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface AgentResult {
+    success: boolean;
+    output: string;
+    filesChanged: string[];
+    diff: string;
+    durationMs: number;
+    error?: string;
+    /** Actual token usage from the agent (if reported). */
+    usage?: TokenUsage;
+}
+export interface AgentRunOptions {
+    task: string;
+    workDir: string;
+    model?: string;
+    files?: string[];
+    signal?: AbortSignal;
+    onOutput?: (chunk: string) => void;
+}
+export interface AgentProvider {
+    readonly name: string;
+    readonly isAvailable: () => Promise<boolean>;
+    run(options: AgentRunOptions): Promise<AgentResult>;
+}
+export type ThreadStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "verification_failed" | "interrupted" | "needs_recovery" | "requires_verification" | "requires_review" | "ready_for_merge";
+export type ThreadProgressPhase = "queued" | "creating_worktree" | "agent_running" | "verifying" | "reviewing" | "capturing_diff" | "compressing" | "completed" | "failed" | "verification_failed" | "cancelled" | "retrying" | "interrupted" | "needs_recovery";
+export interface WorktreeSessionMarker {
+    schemaVersion: 1;
+    sessionId: string;
+    repositoryFingerprint: string;
+    worktreePath: string;
+    branchName: string;
+    threadId: string;
+    ownerToken: string;
+    createdAt: number;
+}
+export interface ThreadConfig {
+    id: string;
+    task: string;
+    context: string;
+    agent: {
+        backend: string;
+        model: string;
+    };
+    files?: string[];
+    focusFiles?: string[];
+    writeScope?: readonly string[];
+    writeScopeDeny?: readonly string[];
+    allowRepositoryWide?: boolean;
+    testCommand?: string;
+    verificationSpec?: VerificationSpec;
+    taskBrief?: TaskBrief;
+    sandboxMode?: "oci-required" | "oci-preferred" | "host-unsafe";
+}
+/** Structured specification for automated verification (Section 16.1). */
+export interface VerificationSpec {
+    readonly schemaVersion?: number;
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly timeoutMs?: number;
+    readonly required?: boolean;
+    readonly network?: "deny" | "allow";
+    readonly allowedOutputPaths?: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cwd?: string;
+    readonly trusted?: boolean;
+    readonly isLegacyString?: boolean;
+}
+/** Immutable execution contract supplied to every subagent. */
+export interface TaskBrief {
+    readonly taskId: string;
+    readonly baseSha: string;
+    readonly objective: string;
+    readonly writeScope: readonly string[];
+    readonly writeScopeDeny?: readonly string[];
+    readonly allowRepositoryWide?: boolean;
+    readonly focusFiles?: readonly string[];
+    readonly testCommand: string;
+    readonly verificationSpec?: VerificationSpec;
+    readonly expectedResult: string;
+    readonly maxAttempts: number;
+    readonly sandboxMode?: "oci-required" | "oci-preferred" | "host-unsafe";
+}
+export type VerificationVerdict = VerificationStatus | "CANCELLED";
+export type ReviewVerdictValue = ReviewStatus;
+export type ExecutionStatus = "QUEUED" | "PREPARING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "TIMED_OUT" | "CANCELLED" | "INTERRUPTED";
+export type VerificationStatus = "NOT_CONFIGURED" | "NOT_APPLICABLE" | "PENDING" | "RUNNING" | "PASS" | "FAIL" | "ERROR" | "TIMEOUT" | "UNAVAILABLE" | "MALFORMED" | "STALE";
+export type ReviewStatus = "NOT_CONFIGURED" | "PENDING" | "RUNNING" | "PASS" | "FAIL" | "ERROR" | "TIMEOUT" | "UNAVAILABLE" | "MALFORMED" | "STALE";
+export type MergeStatus = "NOT_READY" | "READY" | "MERGING" | "MERGED" | "BLOCKED" | "CONFLICT" | "STALE_BASE" | "ERROR";
+export interface VerificationAttestation {
+    schemaVersion: 1;
+    status: VerificationStatus;
+    subject: {
+        repositoryFingerprint: string;
+        baseSha: string;
+        headSha: string;
+        diffSha256: string;
+        scopeSha256: string;
+    };
+    command?: {
+        executable: string;
+        args: string[];
+        cwd: string;
+        timeoutMs: number;
+    };
+    evidence?: {
+        exitCode: number | null;
+        signal: string | null;
+        outputSha256: string;
+        redactedPreview: string;
+        totalTests?: number;
+        passedTests?: number;
+        failedTests?: number;
+    };
+    runnerMode: "oci" | "host-unsafe";
+    startedAt?: number;
+    completedAt?: number;
+    reasonCode?: string;
+}
+export interface ReviewAttestation {
+    schemaVersion: 1;
+    status: ReviewStatus;
+    subject: {
+        repositoryFingerprint: string;
+        baseSha: string;
+        headSha: string;
+        diffSha256: string;
+        scopeSha256: string;
+    };
+    implementerExecutionId: string;
+    reviewerExecutionId: string;
+    provider: string;
+    model: string;
+    independenceLevel: "same_process" | "separate_process" | "isolated_container" | "external_evaluator";
+    rawOutputDigest: string;
+    staticFindings?: Array<{
+        ruleId: string;
+        severity: string;
+        message: string;
+        file?: string;
+        line?: number;
+    }>;
+    llmVerdict?: {
+        specCompliance: string;
+        codeQuality: string;
+        summary: string;
+    };
+    retries: number;
+    startedAt?: number;
+    completedAt?: number;
+}
+export interface ReviewVerdict {
+    readonly reviewerId: string;
+    readonly specCompliance: ReviewVerdictValue;
+    readonly codeQuality: ReviewVerdictValue;
+    readonly summary: string;
+    readonly reviewedAt: number;
+}
+export interface ThreadState {
+    id: string;
+    config: ThreadConfig;
+    status: ThreadStatus;
+    phase: ThreadProgressPhase;
+    worktreePath?: string;
+    branchName?: string;
+    result?: CompressedResult;
+    startedAt?: number;
+    completedAt?: number;
+    error?: string;
+    attempt: number;
+    maxAttempts: number;
+    estimatedCostUsd: number;
+    taskBrief?: TaskBrief;
+    verification?: VerificationVerdict;
+    review?: ReviewVerdict;
+    scopeViolation?: boolean;
+    revision?: number;
+    executionStatus?: ExecutionStatus;
+    verificationStatus?: VerificationStatus;
+    reviewStatus?: ReviewStatus;
+    mergeStatus?: MergeStatus;
+    verificationAttestation?: VerificationAttestation;
+    reviewAttestation?: ReviewAttestation;
+}
+export interface CompressedResult {
+    success: boolean;
+    summary: string;
+    filesChanged: string[];
+    diffStats: string;
+    durationMs: number;
+    estimatedCostUsd: number;
+    /** Actual token usage (when available from agent). */
+    usage?: TokenUsage;
+    /** Whether cost is based on real usage or estimates. */
+    costIsEstimate?: boolean;
+}
+export interface WorktreeInfo {
+    id: string;
+    path: string;
+    branch: string;
+}
+export interface MergeResult {
+    success: boolean;
+    branch: string;
+    conflicts: string[];
+    conflictDiff: string;
+    message: string;
+}
+export interface BudgetState {
+    totalSpentUsd: number;
+    totalReservedUsd?: number;
+    threadCosts: Map<string, number>;
+    sessionLimitUsd: number;
+    perThreadLimitUsd: number;
+    /** Total tokens consumed across all threads. */
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+    /** Number of threads with actual (non-estimated) cost data. */
+    actualCostThreads: number;
+    /** Number of threads with estimated cost data. */
+    estimatedCostThreads: number;
+}
+/** Rough per-1M-token pricing for cost estimation. */
+export declare const MODEL_PRICING: Record<string, {
+    input: number;
+    output: number;
+}>;
+export type { ModelSlots, SwarmConfig } from "../config.js";
+export interface ThreadRequestMessage {
+    type: "thread_request";
+    id: string;
+    task: string;
+    context: string;
+    agent_backend: string;
+    model: string;
+    files: string[];
+}
+export interface ThreadResultMessage {
+    type: "thread_result";
+    id: string;
+    result: string;
+    success: boolean;
+    files_changed: string[];
+    duration_ms: number;
+}
+export interface MergeRequestMessage {
+    type: "merge_request";
+    id: string;
+}
+export interface MergeResultMessage {
+    type: "merge_result";
+    id: string;
+    result: string;
+    success: boolean;
+}

package/dist/core/types.js

@@ -0,0 +1,19 @@
+/**
+ * Shared type definitions for swarm-code.
+ */
+/** Rough per-1M-token pricing for cost estimation. */
+export const MODEL_PRICING = {
+    // Anthropic
+    "claude-sonnet-4-6": { input: 3, output: 15 },
+    "claude-opus-4-6": { input: 15, output: 75 },
+    "claude-haiku-4-5": { input: 0.8, output: 4 },
+    // OpenAI
+    "gpt-4o": { input: 2.5, output: 10 },
+    "gpt-4o-mini": { input: 0.15, output: 0.6 },
+    o3: { input: 10, output: 40 },
+    "o3-mini": { input: 1.1, output: 4.4 },
+    // Google
+    "gemini-2.5-pro": { input: 1.25, output: 10 },
+    "gemini-2.5-flash": { input: 0.15, output: 0.6 },
+};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgUH,sDAAsD;AACtD,MAAM,CAAC,MAAM,aAAa,GAAsD;IAC/E,YAAY;IACZ,mBAAmB,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE;IAC7C,iBAAiB,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IAC5C,kBAAkB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE;IAC7C,SAAS;IACT,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE;IACpC,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IAC3C,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;IAC7B,SAAS,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;IACtC,SAAS;IACT,gBAAgB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;IAC7C,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;CAChD,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Load env vars into process.env.
+ * Must be imported BEFORE any module that reads env vars (e.g. pi-ai).
+ *
+ * Priority (highest wins):
+ *   1. Shell environment variables (already in process.env)
+ *   2. .env in package root
+ *   3. ~/.rlm/credentials — persistent keys saved by first-run setup
+ */
+export {};

package/dist/env.js

@@ -0,0 +1,75 @@
+/**
+ * Load env vars into process.env.
+ * Must be imported BEFORE any module that reads env vars (e.g. pi-ai).
+ *
+ * Priority (highest wins):
+ *   1. Shell environment variables (already in process.env)
+ *   2. .env in package root
+ *   3. ~/.rlm/credentials — persistent keys saved by first-run setup
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+function parseEnvFile(filePath) {
+    const vars = new Map();
+    if (!fs.existsSync(filePath))
+        return vars;
+    const content = fs.readFileSync(filePath, "utf-8");
+    for (const rawLine of content.split("\n")) {
+        let trimmed = rawLine.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        // Strip leading "export " (common in .env files)
+        if (trimmed.startsWith("export "))
+            trimmed = trimmed.slice(7);
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Strip matching surrounding quotes ("..." or '...')
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key)
+            vars.set(key, value);
+    }
+    return vars;
+}
+// Collect file-based vars: credentials first, .env overwrites
+const fileVars = new Map();
+// 1. Load persistent credentials (lowest priority file)
+// Check both swarm and rlm credential locations
+const credVars = parseEnvFile(path.join(os.homedir(), ".swarm", "credentials"));
+const rlmCreds = parseEnvFile(path.join(os.homedir(), ".rlm", "credentials"));
+for (const [k, v] of rlmCreds) {
+    if (!credVars.has(k))
+        credVars.set(k, v);
+}
+for (const [k, v] of credVars)
+    fileVars.set(k, v);
+// 2. Load .env from package root (overwrites credentials)
+const __dir = path.dirname(fileURLToPath(import.meta.url));
+const dotenvVars = parseEnvFile(path.resolve(__dir, "..", ".env"));
+for (const [k, v] of dotenvVars)
+    fileVars.set(k, v);
+// 3. Apply: only set if NOT already in shell env (shell always wins)
+for (const [key, value] of fileVars) {
+    if (!process.env[key]) {
+        process.env[key] = value;
+    }
+}
+// Alias: GOOGLE_API_KEY → GEMINI_API_KEY (pi-ai expects GEMINI_API_KEY)
+// Remove GOOGLE_API_KEY after aliasing to avoid pi-ai "both set" warning
+if (process.env.GOOGLE_API_KEY) {
+    if (!process.env.GEMINI_API_KEY) {
+        process.env.GEMINI_API_KEY = process.env.GOOGLE_API_KEY;
+    }
+    delete process.env.GOOGLE_API_KEY;
+}
+// Default model
+if (!process.env.RLM_MODEL) {
+    process.env.RLM_MODEL = "claude-sonnet-4-6";
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"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"}

package/dist/hooks/runner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hook runner — executes user-defined commands at lifecycle points.
+ *
+ * Hooks provide deterministic control flow (not LLM-decided).
+ * They run shell commands and surface only errors — success is silent.
+ *
+ * Lifecycle points:
+ *   - post_thread: After a thread commits (before compression)
+ *   - post_merge: After merge_threads() completes
+ *   - post_session: When the session ends
+ */
+export interface HookConfig {
+    command: string;
+    on_failure: "warn" | "block";
+}
+export interface HooksConfig {
+    post_thread: HookConfig[];
+    post_merge: HookConfig[];
+    post_session: HookConfig[];
+}
+export interface HookResult {
+    success: boolean;
+    output: string;
+    command: string;
+}
+export interface LoadHooksOptions {
+    allow_hooks?: boolean;
+}
+export interface RunHooksOptions {
+    allow_hooks?: boolean;
+}
+/**
+ * Load hooks from .swarm/hooks.yaml or .agents/hooks.json.
+ * If hook files exist and allow_hooks is false (default), execution is blocked
+ * and a structured warning is emitted.
+ */
+export declare function loadHooks(projectDir: string, allowHooksOrOptions?: boolean | LoadHooksOptions): HooksConfig;
+/**
+ * Run hooks for a lifecycle point.
+ * Returns results for each hook. On "block" failure, throws.
+ * Success output is swallowed — only errors are surfaced.
+ */
+export declare function runHooks(hooks: HookConfig[], cwd: string, label: string, allowHooksOrOptions?: boolean | RunHooksOptions): HookResult[];

package/dist/hooks/runner.js

@@ -0,0 +1,173 @@
+/**
+ * Hook runner — executes user-defined commands at lifecycle points.
+ *
+ * Hooks provide deterministic control flow (not LLM-decided).
+ * They run shell commands and surface only errors — success is silent.
+ *
+ * Lifecycle points:
+ *   - post_thread: After a thread commits (before compression)
+ *   - post_merge: After merge_threads() completes
+ *   - post_session: When the session ends
+ */
+import { execSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const DEFAULT_HOOKS = {
+    post_thread: [],
+    post_merge: [],
+    post_session: [],
+};
+/**
+ * Load hooks from .swarm/hooks.yaml or .agents/hooks.json.
+ * If hook files exist and allow_hooks is false (default), execution is blocked
+ * and a structured warning is emitted.
+ */
+export function loadHooks(projectDir, allowHooksOrOptions = false) {
+    const allowHooks = typeof allowHooksOrOptions === "boolean" ? allowHooksOrOptions : Boolean(allowHooksOrOptions?.allow_hooks);
+    const swarmHooksFile = path.join(projectDir, ".swarm", "hooks.yaml");
+    const agentsHooksFile = path.join(projectDir, ".agents", "hooks.json");
+    const hasSwarmHooks = fs.existsSync(swarmHooksFile);
+    const hasAgentsHooks = fs.existsSync(agentsHooksFile);
+    if (!hasSwarmHooks && !hasAgentsHooks) {
+        return { ...DEFAULT_HOOKS };
+    }
+    if (!allowHooks) {
+        console.warn("[hooks] Hooks execution is disabled by default. Pass --allow-hooks or set allow_hooks: true in config to enable.");
+        return { ...DEFAULT_HOOKS };
+    }
+    const hooks = { post_thread: [], post_merge: [], post_session: [] };
+    if (hasSwarmHooks) {
+        try {
+            const raw = fs.readFileSync(swarmHooksFile, "utf-8");
+            const parsed = parseHooksYaml(raw);
+            hooks.post_thread.push(...parsed.post_thread);
+            hooks.post_merge.push(...parsed.post_merge);
+            hooks.post_session.push(...parsed.post_session);
+        }
+        catch {
+            // ignore malformed file
+        }
+    }
+    if (hasAgentsHooks) {
+        try {
+            const raw = fs.readFileSync(agentsHooksFile, "utf-8");
+            const parsed = parseHooksJson(raw);
+            hooks.post_thread.push(...parsed.post_thread);
+            hooks.post_merge.push(...parsed.post_merge);
+            hooks.post_session.push(...parsed.post_session);
+        }
+        catch {
+            // ignore malformed file
+        }
+    }
+    return hooks;
+}
+function parseHooksJson(raw) {
+    const hooks = { post_thread: [], post_merge: [], post_session: [] };
+    try {
+        const parsed = JSON.parse(raw);
+        const target = parsed?.hooks && typeof parsed.hooks === "object" ? parsed.hooks : parsed;
+        const sections = ["post_thread", "post_merge", "post_session"];
+        for (const section of sections) {
+            const list = target[section];
+            if (!Array.isArray(list))
+                continue;
+            for (const item of list) {
+                if (typeof item === "string" && item.trim()) {
+                    hooks[section].push({ command: item.trim(), on_failure: "warn" });
+                }
+                else if (item && typeof item === "object" && typeof item.command === "string") {
+                    hooks[section].push({
+                        command: item.command.trim(),
+                        on_failure: item.on_failure === "block" ? "block" : "warn",
+                    });
+                }
+            }
+        }
+        if (Array.isArray(target)) {
+            for (const item of target) {
+                if (item && typeof item === "object" && typeof item.command === "string" && typeof item.event === "string") {
+                    if (item.event === "post_thread" || item.event === "post_merge" || item.event === "post_session") {
+                        hooks[item.event].push({
+                            command: item.command.trim(),
+                            on_failure: item.on_failure === "block" ? "block" : "warn",
+                        });
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // return empty on invalid JSON
+    }
+    return hooks;
+}
+function parseHooksYaml(raw) {
+    const hooks = { post_thread: [], post_merge: [], post_session: [] };
+    let currentSection = null;
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        if (trimmed === "post_thread:" || trimmed === "post_merge:" || trimmed === "post_session:") {
+            currentSection = trimmed.replace(":", "");
+            continue;
+        }
+        if (currentSection && trimmed.startsWith("- command:")) {
+            let command = trimmed.replace("- command:", "").trim();
+            if ((command.startsWith('"') && command.endsWith('"')) || (command.startsWith("'") && command.endsWith("'"))) {
+                command = command.slice(1, -1);
+            }
+            if (command) {
+                hooks[currentSection].push({ command, on_failure: "warn" });
+            }
+        }
+        if (currentSection && trimmed.startsWith("on_failure:")) {
+            const val = trimmed.replace("on_failure:", "").trim();
+            const last = hooks[currentSection][hooks[currentSection].length - 1];
+            if (last && (val === "warn" || val === "block")) {
+                last.on_failure = val;
+            }
+        }
+    }
+    return hooks;
+}
+/**
+ * Run hooks for a lifecycle point.
+ * Returns results for each hook. On "block" failure, throws.
+ * Success output is swallowed — only errors are surfaced.
+ */
+export function runHooks(hooks, cwd, label, allowHooksOrOptions = true) {
+    if (!hooks || hooks.length === 0) {
+        return [];
+    }
+    const allowHooks = typeof allowHooksOrOptions === "boolean" ? allowHooksOrOptions : (allowHooksOrOptions?.allow_hooks ?? true);
+    if (!allowHooks) {
+        console.warn(`[hooks] Hooks execution is disabled. Skipping ${label} hooks.`);
+        return [];
+    }
+    const results = [];
+    for (const hook of hooks) {
+        try {
+            execSync(hook.command, {
+                cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 60_000,
+                encoding: "utf-8",
+            });
+            // Success — silent (context-efficient per harness engineering best practice)
+            results.push({ success: true, output: "", command: hook.command });
+        }
+        catch (err) {
+            const stderr = err.stderr || err.stdout || err.message || "unknown error";
+            // Only surface error output
+            const output = `[${label}] Hook failed: ${hook.command}\n${stderr}`.trim();
+            results.push({ success: false, output, command: hook.command });
+            if (hook.on_failure === "block") {
+                throw new Error(output);
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=runner.js.map

package/dist/hooks/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/hooks/runner.ts"],"names":[],"mappings":"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"}

package/dist/labs/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+/**
+ * Standalone RLM CLI — run Recursive Language Model queries from the terminal.
+ *
+ * Usage:
+ *   npx tsx src/cli.ts --file large-file.txt "What are the main themes?"
+ *   npx tsx src/cli.ts --url https://example.com/big.txt "Summarize this"
+ *   cat data.txt | npx tsx src/cli.ts --stdin "Count the errors"
+ *
+ * Environment (pick one):
+ *   ANTHROPIC_API_KEY — for Anthropic models
+ *   OPENAI_API_KEY    — for OpenAI models
+ *   GEMINI_API_KEY    — for Google models
+ */
+import "./env.js";