@oxagen/cli 0.5.0 → 0.6.1

package/dist/agent/env.js

@@ -0,0 +1,82 @@
+/**
+ * Gateway credential resolution.
+ *
+ * The local agent loop talks to the Vercel AI Gateway (same gateway the rest of
+ * the platform uses — see the `ai-gateway-only` policy). The AI SDK reads
+ * `AI_GATEWAY_API_KEY` from the environment automatically, so all we need to do
+ * is make sure it is present before the first model call.
+ *
+ * Resolution order:
+ *   1. `AI_GATEWAY_API_KEY` already in the process environment.
+ *   2. `gatewayKey` in `~/.config/oxagen/config.json`.
+ *   3. The nearest `.env.local` walking up from the current working directory
+ *      (so running `oxagen` from inside the monorepo "just works").
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, parse as parsePath } from "node:path";
+import { readConfig } from "../lib/config.js";
+const ENV_VAR = "AI_GATEWAY_API_KEY";
+/** Thrown when no gateway credential can be resolved anywhere. */
+export class MissingGatewayKeyError extends Error {
+    constructor() {
+        super("No AI_GATEWAY_API_KEY found. Set it in your shell, in ~/.config/oxagen/config.json " +
+            '("gatewayKey"), or in a .env.local above the working directory.');
+        this.name = "MissingGatewayKeyError";
+    }
+}
+function findInEnvLocal(startDir) {
+    let dir = startDir;
+    const { root } = parsePath(startDir);
+    // Walk up to the filesystem root looking for a .env.local that defines the key.
+    for (;;) {
+        const candidate = join(dir, ".env.local");
+        if (existsSync(candidate)) {
+            try {
+                const text = readFileSync(candidate, "utf8");
+                for (const line of text.split("\n")) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed.startsWith("#"))
+                        continue;
+                    const eq = trimmed.indexOf("=");
+                    if (eq === -1)
+                        continue;
+                    if (trimmed.slice(0, eq).trim() !== ENV_VAR)
+                        continue;
+                    // Strip surrounding quotes (loadEnv-style over-quoting is common here).
+                    return trimmed
+                        .slice(eq + 1)
+                        .trim()
+                        .replace(/^["']|["']$/g, "");
+                }
+            }
+            catch {
+                /* unreadable .env.local — keep walking up */
+            }
+        }
+        if (dir === root)
+            return undefined;
+        dir = dirname(dir);
+    }
+}
+/**
+ * Ensure `AI_GATEWAY_API_KEY` is set in `process.env`, resolving it from config
+ * or a nearby `.env.local` if needed. Returns the key, or `null` if it could
+ * not be found anywhere.
+ */
+export function ensureGatewayKey(cwd = process.cwd()) {
+    const fromEnv = process.env[ENV_VAR];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    const fromConfig = readConfig().gatewayKey;
+    if (fromConfig && fromConfig.length > 0) {
+        process.env[ENV_VAR] = fromConfig;
+        return fromConfig;
+    }
+    const fromFile = findInEnvLocal(cwd);
+    if (fromFile && fromFile.length > 0) {
+        process.env[ENV_VAR] = fromFile;
+        return fromFile;
+    }
+    return null;
+}
+//# sourceMappingURL=env.js.map

package/dist/agent/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/agent/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAErC,kEAAkE;AAClE,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C;QACE,KAAK,CACH,qFAAqF;YACnF,iEAAiE,CACpE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED,SAAS,cAAc,CAAC,QAAgB;IACtC,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACrC,gFAAgF;IAChF,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QAC1C,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;gBAC7C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBACpC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,SAAS;oBAClD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;oBAChC,IAAI,EAAE,KAAK,CAAC,CAAC;wBAAE,SAAS;oBACxB,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,OAAO;wBAAE,SAAS;oBACtD,wEAAwE;oBACxE,OAAO,OAAO;yBACX,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC;yBACb,IAAI,EAAE;yBACN,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;gBACjC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,6CAA6C;YAC/C,CAAC;QACH,CAAC;QACD,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACnC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAElD,MAAM,UAAU,GAAG,UAAU,EAAE,CAAC,UAAU,CAAC;IAC3C,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC;QAClC,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC;QAChC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/agent/evaluator.d.ts

@@ -0,0 +1,13 @@
+import type { PromptEvaluation } from "./trace.js";
+export interface EvaluatePromptOptions {
+    prompt: string;
+    /** Override the evaluator model slug (otherwise the fast tier). */
+    model?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Evaluate a prompt with the cheap model. Returns the model's structured read, or
+ * a heuristic fallback that never throws — the pipeline must always make progress.
+ */
+export declare function evaluatePrompt(opts: EvaluatePromptOptions): Promise<PromptEvaluation>;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/agent/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../src/agent/evaluator.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA4DnD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAiDD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CA6B3B"}

package/dist/agent/evaluator.js

@@ -0,0 +1,150 @@
+/**
+ * Prompt evaluator — the cheap front-of-pipeline model call.
+ *
+ * Before the expensive coding model ever sees a prompt, a small, fast model
+ * (Haiku by default) reads it and reports back:
+ *   - completeness: is this actionable on its own, or is it missing what/where/done?
+ *   - complexity:   how much work / risk / blast-radius does it imply?
+ *   - a recommended tier for the executor,
+ *   - the symbols / files / topics worth pulling from the code graph,
+ *   - a refined prompt with filler removed and intent sharpened (meaning intact),
+ *   - and its chain of thought.
+ *
+ * This is what lets the CLI spend Haiku money to decide how to spend Opus money,
+ * and to enrich a vague prompt before acting on it. It NEVER blocks a turn: if
+ * the model call fails, a transparent heuristic fallback (the deterministic cost
+ * router) keeps the pipeline moving.
+ */
+import { generateObject } from "ai";
+import { z } from "zod";
+import { classifyTier, modelForTier, accumulateUsage } from "./model-router.js";
+import { emptyUsage } from "./fleet/types.js";
+/** A tier's evaluator-model slug, overridable to track gateway drift. */
+function evaluatorModel(override) {
+    return (override ??
+        process.env["OXAGEN_LLM_EVALUATOR"] ??
+        modelForTier("fast"));
+}
+const evalSchema = z.object({
+    completeness: z
+        .number()
+        .min(0)
+        .max(100)
+        .describe("0–100. How complete/actionable is the prompt ON ITS OWN? 100 = names what " +
+        "to change, where, and how to know it's done. Low = vague or missing key facts."),
+    complexity: z
+        .number()
+        .min(0)
+        .max(100)
+        .describe("0–100. How much work/risk/blast-radius does this imply? Trivial one-liner ≈ 10; " +
+        "multi-file feature ≈ 60; auth/billing/migration/architecture ≈ 90."),
+    recommendedTier: z
+        .enum(["fast", "balanced", "precise"])
+        .describe("YOU are choosing the actual worker model that will build this, and it costs real " +
+        "money. Pick the CHEAPEST tier that still delivers a correct, high-quality result " +
+        "— lean cheap, never overspend: 'fast' mechanical/single-file, 'balanced' normal " +
+        "feature work, 'precise' auth/billing/security/migration/architecture or wide blast-radius."),
+    missing: z
+        .array(z.string())
+        .describe("Specific information the prompt lacks to be fully actionable. Empty if none."),
+    contextQueries: z
+        .array(z.string())
+        .describe("Symbol names, file paths, or short topics worth retrieving from the repo's code " +
+        "graph to ground the work (e.g. 'loginUser', 'src/auth/session.ts'). Empty if none."),
+    refinedPrompt: z
+        .string()
+        .describe("The prompt rewritten for the coding agent: remove pleasantries, hedging, and " +
+        "redundancy; sharpen the ask. PRESERVE EVERY real requirement and constraint — " +
+        "never invent, never drop intent. If the prompt is already tight, return it unchanged."),
+    removed: z
+        .array(z.string())
+        .describe("Phrases removed from the original because they add no value. Empty if none."),
+    reasoning: z
+        .string()
+        .describe("2–4 sentence explanation of the scores and what context will help."),
+});
+const EVALUATOR_SYSTEM = [
+    "You are the evaluation stage of an agentic coding system. A coding agent is about",
+    "to act on the user's prompt against a real repository. Your job is to triage it.",
+    "",
+    "Score it honestly:",
+    "- completeness: can the agent act on this WITHOUT guessing? Penalize missing files,",
+    "  undefined terms, and 'fix it' with no symptom. Reward concrete targets and acceptance.",
+    "- complexity: estimate the work, risk, and blast radius — not the prompt's length.",
+    "",
+    "Then help the agent succeed:",
+    "- recommendedTier: YOU choose the worker model that builds this, and it spends real",
+    "  money. Pick the CHEAPEST tier that still produces a correct, high-quality result —",
+    "  lean cheap and escalate only when the task truly needs it. Reserve 'precise' for",
+    "  auth, billing, security, migrations, schema, or architecture.",
+    "- contextQueries: name the exact symbols/files/topics the agent should pull from the",
+    "  code graph so it skips blind exploration. Prefer real identifiers and paths.",
+    "- refinedPrompt: rewrite for the agent. Strip filler and contradiction; keep 100% of the",
+    "  actual intent and every constraint. Do NOT add requirements the user did not state.",
+].join("\n");
+/**
+ * Build the deterministic heuristic evaluation used when the model is unavailable
+ * or the call fails. Uses the cost router so the tier is still sensible, and never
+ * mutates the prompt (a safe fallback must not risk dropping intent).
+ */
+function heuristicEvaluation(prompt, model) {
+    const route = classifyTier({ text: prompt });
+    const complexity = route.tier === "precise" ? 85 : route.tier === "balanced" ? 55 : 20;
+    // Longer, more specific prompts are treated as more complete; very short asks less so.
+    const len = prompt.trim().length;
+    const completeness = len < 40 ? 45 : len < 160 ? 65 : 80;
+    return {
+        completeness,
+        complexity,
+        recommendedTier: route.tier,
+        missing: [],
+        contextQueries: [],
+        refinedPrompt: prompt,
+        removed: [],
+        reasoning: `Heuristic evaluation (model unavailable): ${route.rationale}.`,
+        fallback: true,
+        model,
+        usage: emptyUsage(),
+    };
+}
+/**
+ * Evaluate a prompt with the cheap model. Returns the model's structured read, or
+ * a heuristic fallback that never throws — the pipeline must always make progress.
+ */
+export async function evaluatePrompt(opts) {
+    const model = evaluatorModel(opts.model);
+    try {
+        const { object, usage } = await generateObject({
+            model,
+            schema: evalSchema,
+            system: EVALUATOR_SYSTEM,
+            prompt: `Prompt to evaluate:\n${opts.prompt}`,
+            abortSignal: opts.signal,
+        });
+        // A refined prompt that came back empty would silently drop the user's intent —
+        // fall back to the original text in that case.
+        const refinedPrompt = object.refinedPrompt.trim() || opts.prompt;
+        return {
+            completeness: clamp(object.completeness),
+            complexity: clamp(object.complexity),
+            recommendedTier: object.recommendedTier,
+            missing: object.missing,
+            contextQueries: object.contextQueries,
+            refinedPrompt,
+            removed: object.removed,
+            reasoning: object.reasoning,
+            fallback: false,
+            model,
+            usage: accumulateUsage(emptyUsage(), model, usage),
+        };
+    }
+    catch {
+        return heuristicEvaluation(opts.prompt, model);
+    }
+}
+function clamp(n) {
+    if (Number.isNaN(n))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(n)));
+}
+//# sourceMappingURL=evaluator.js.map

package/dist/agent/evaluator.js.map

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

package/dist/agent/fleet/git-isolation.d.ts

@@ -0,0 +1,142 @@
+/** Result of one git invocation. Never throws — the exit code is returned. */
+export interface GitResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+/** Runs git with the given args in `cwd`. Injectable for tests. */
+export type GitRunner = (args: string[], cwd?: string) => Promise<GitResult>;
+/** The real runner: `git <args>` via child_process, rooted at the repo. */
+export declare function defaultGitRunner(repoRoot: string): GitRunner;
+/** Outcome of integrating one task branch into the integration branch. */
+export interface IntegrationResult {
+    /** True when the task branch merged cleanly (or had nothing new to merge). */
+    ok: boolean;
+    /** Integration branch tip after a clean merge. */
+    commit?: string;
+    /** Conflicting files (relative paths) when `ok` is false. */
+    conflicts?: string[];
+    /** The task branch that was being integrated. */
+    taskBranch: string;
+    /** The pinned task tip — always recoverable, even on conflict. */
+    taskTip?: string;
+    /** True when `rerere` auto-applied a previously-recorded resolution. */
+    autoResolved?: boolean;
+}
+/** A pinned atomic commit produced by an agent. */
+export interface Checkpoint {
+    taskId: string;
+    hash: string;
+    /** Durable ref keeping the commit reachable forever. */
+    ref: string;
+    message: string;
+}
+/**
+ * The isolation surface the fleet depends on. {@link WorktreeManager} is the
+ * real implementation; tests inject a fake satisfying this interface so the
+ * orchestrator's own unit tests never touch git or the filesystem.
+ */
+export interface Isolation {
+    init(): Promise<void>;
+    spawn(taskId: string): Promise<string>;
+    checkpoint(taskId: string, message: string): Promise<Checkpoint | null>;
+    recordedCommits(taskId: string): readonly Checkpoint[];
+    integrate(taskId: string, message?: string): Promise<IntegrationResult>;
+    integrationRef(): {
+        path: string;
+        branch: string;
+    } | null;
+    dispose(taskId: string, opts?: {
+        keep?: boolean;
+    }): Promise<void>;
+    cleanupAll(): Promise<void>;
+}
+export interface WorktreeManagerOptions {
+    /** Any path inside the repo; the real toplevel is resolved in {@link init}. */
+    repoRoot: string;
+    /** Ref namespace for this fleet run's branches/pins (e.g. the plan id). */
+    namespace?: string;
+    /** Where worktrees are created (default `<repo>/.oxagen/worktrees`). */
+    root?: string;
+    /** Inject a fake git for tests; defaults to {@link defaultGitRunner}. */
+    git?: GitRunner;
+}
+/**
+ * Owns the worktrees, branches, and durability pins for one fleet run.
+ *
+ * One instance per {@link Fleet}. Methods are safe to call from many concurrent
+ * agents: `spawn`/`checkpoint`/`dispose` operate on disjoint worktrees, and
+ * `integrate` is serialized internally so two merges never race on the
+ * integration branch.
+ */
+export declare class WorktreeManager implements Isolation {
+    private readonly opts;
+    private readonly git;
+    private readonly ns;
+    private repoRoot;
+    private root;
+    /** The frozen commit every task branch is cut from. */
+    private baseRef;
+    /** Lazily-created integration worktree path + branch. */
+    private integration;
+    private initialized;
+    /** Per-task pin sequence + recorded checkpoints (the durability log). */
+    private readonly seq;
+    private readonly commits;
+    /** Worktrees handed out, by task id. */
+    private readonly worktrees;
+    /** Serializes `integrate` so concurrent finishers can't race the merge. */
+    private integrateLock;
+    constructor(opts: WorktreeManagerOptions);
+    /**
+     * Resolve the repo toplevel, freeze the base ref, enable `rerere`, and keep
+     * the worktree root out of git's sight. Idempotent.
+     */
+    init(): Promise<void>;
+    /** The frozen base every task fans out from. */
+    get base(): string;
+    /**
+     * Create an isolated worktree for `taskId` and return its path. The agent runs
+     * with this as its `cwd`; nothing it does can touch another agent's tree.
+     */
+    spawn(taskId: string): Promise<string>;
+    /**
+     * Atomically commit whatever the agent changed in its worktree and pin the
+     * commit under `refs/oxagen/agents/<task>/<n>`. Returns the checkpoint, or
+     * `null` when the agent changed nothing.
+     */
+    checkpoint(taskId: string, message: string): Promise<Checkpoint | null>;
+    /** Every pinned checkpoint recorded for a task — the durability log. */
+    recordedCommits(taskId: string): readonly Checkpoint[];
+    /**
+     * Merge a task's branch into the integration branch. Serialized so two merges
+     * never race. A conflicting merge is aborted (integration tree left clean) and
+     * the conflicting files are returned — never a corrupt half-merge.
+     */
+    integrate(taskId: string, message?: string): Promise<IntegrationResult>;
+    private doIntegrate;
+    /** The integration branch + its worktree path, once at least one integrate ran. */
+    integrationRef(): {
+        path: string;
+        branch: string;
+    } | null;
+    /**
+     * Remove a task's worktree. Keeps the branch and the `refs/oxagen/agents` pins
+     * (so nothing is lost). Pass `keep` to leave the worktree on disk — e.g. after
+     * a conflict, so a resolver agent or human can work in it.
+     */
+    dispose(taskId: string, opts?: {
+        keep?: boolean;
+    }): Promise<void>;
+    /**
+     * Tear down every worktree and prune. Keeps the integration branch (the
+     * result) and all `refs/oxagen/agents` pins (the durability log).
+     */
+    cleanupAll(): Promise<void>;
+    private ensureIntegration;
+    private removeWorktree;
+    private withIntegrateLock;
+    /** Keep `.oxagen/` out of git's untracked list without touching tracked .gitignore. */
+    private excludeWorktreeRoot;
+}
+//# sourceMappingURL=git-isolation.d.ts.map

package/dist/agent/fleet/git-isolation.d.ts.map

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