@oxagen/cli 0.5.0 → 0.6.1

package/dist/agent/pipeline.js

@@ -0,0 +1,371 @@
+import { runAgent } from "./loop.js";
+import { ensureGatewayKey, MissingGatewayKeyError } from "./env.js";
+import { evaluatePrompt } from "./evaluator.js";
+import { judgeCompleteness, buildRevisionPrompt } from "./judge.js";
+import { enhancePrompt } from "./prompt-enhancer.js";
+import { classifyTier, modelForTier, tierForSlug, tierLabel, accumulateUsage, } from "./model-router.js";
+import { emptyUsage } from "./fleet/types.js";
+export { MissingGatewayKeyError };
+const TIER_RANK = { fast: 0, balanced: 1, precise: 2 };
+/** Cap stored free-text so a single trace file can't grow without bound. */
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max) + "…" : s;
+}
+let traceCounter = 0;
+function newTraceId() {
+    traceCounter = (traceCounter + 1) % 1_000_000;
+    return `turn_${Date.now().toString(36)}_${traceCounter.toString(36)}`;
+}
+/** Pull the file path from a write/edit tool call, or a command from bash. */
+function collectActivity(name, input, files, commands) {
+    const obj = (input ?? {});
+    if ((name === "write_file" || name === "edit_file") && typeof obj.path === "string") {
+        files.add(obj.path);
+    }
+    if (name === "bash") {
+        const cmd = obj.command ?? obj.cmd;
+        if (typeof cmd === "string")
+            commands.push(truncate(cmd, 120));
+    }
+}
+/**
+ * Run one prompt through the full pipeline. Throws {@link MissingGatewayKeyError}
+ * if no gateway credential can be resolved; otherwise always produces a trace.
+ */
+export async function runTurn(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    if (!ensureGatewayKey(cwd))
+        throw new MissingGatewayKeyError();
+    const startedAt = Date.now();
+    const filesTouched = new Set();
+    const commandsRun = [];
+    const onToolCall = (name, input) => {
+        collectActivity(name, input, filesTouched, commandsRun);
+        opts.onToolCall?.(name, input);
+    };
+    // Verbose telemetry accumulators (left empty/undefined when verbose is off).
+    const phases = [];
+    const toolEvents = [];
+    const onToolEvent = opts.verbose ? (e) => void toolEvents.push(e) : undefined;
+    // ── Bare mode: skip the pipeline, run the agent directly. ──
+    if (opts.bare) {
+        return runBare(opts, cwd, startedAt, filesTouched, commandsRun, onToolCall, onToolEvent, toolEvents);
+    }
+    let usage = emptyUsage();
+    // ── 1. EVALUATE ──
+    const evalStart = Date.now();
+    const evaluation = await evaluatePrompt({ prompt: opts.prompt, signal: opts.signal });
+    phases.push(phaseStat("evaluate", 0, evalStart, evaluation.model, evaluation.usage));
+    usage = mergeUsage(usage, evaluation.usage);
+    opts.onStage?.({
+        kind: "evaluate",
+        label: `evaluated · completeness ${evaluation.completeness}/100 · complexity ${evaluation.complexity}/100`,
+        detail: evaluation.fallback ? "heuristic" : evaluation.model.split("/").pop(),
+    });
+    // ── 2. ENHANCE ──
+    const enhanceStart = Date.now();
+    const enhanced = await enhancePrompt({
+        prompt: evaluation.refinedPrompt,
+        cwd,
+        memory: opts.fleetMemory ?? null,
+        extraQueries: evaluation.contextQueries,
+    });
+    phases.push(phaseStat("enhance", 0, enhanceStart, undefined, emptyUsage()));
+    const enhancement = {
+        prompt: enhanced.prompt,
+        context: enhanced.context,
+        resolved: enhanced.resolved,
+        lessonCount: enhanced.lessons.length,
+        source: enhancementSource(enhanced.resolved.length, enhanced.lessons.length),
+        startedAt: enhanced.startedAt,
+        finishedAt: enhanced.finishedAt,
+        durationMs: enhanced.durationMs,
+        retrieval: enhanced.retrieval,
+    };
+    opts.onStage?.({
+        kind: "enhance",
+        label: enhanced.resolved.length || enhanced.lessons.length
+            ? `enhanced · ${enhanced.resolved.length} code refs · ${enhanced.lessons.length} lessons`
+            : "enhanced · no extra context found",
+    });
+    // ── 3. ROUTE ──
+    const routeStart = Date.now();
+    const routed = selectModel(opts.model, evaluation);
+    phases.push(phaseStat("route", 0, routeStart, undefined, emptyUsage()));
+    opts.onStage?.({
+        kind: "route",
+        label: `model · ${tierLabel(routed.tier)} (${routed.model.split("/").pop()})`,
+        detail: routed.rationale,
+    });
+    // ── 4. EXECUTE (+ 5. JUDGE / 6. REVISE loop) ──
+    const maxRounds = Math.max(0, opts.maxReviseRounds ?? 1);
+    const judgeRounds = [];
+    let history = opts.history ?? [];
+    let prompt = enhanced.prompt;
+    let lastText = "";
+    let totalSteps = 0;
+    for (let round = 0;; round++) {
+        if (round > 0) {
+            opts.onStage?.({ kind: "revise", label: `revising · round ${round} (incomplete work)` });
+        }
+        opts.onStage?.({
+            kind: "execute",
+            label: round === 0 ? "executing" : `executing · revision ${round}`,
+        });
+        const execStart = Date.now();
+        const result = await runAgent({
+            prompt,
+            history,
+            cwd,
+            model: routed.model,
+            maxSteps: opts.maxSteps,
+            projectContext: opts.projectContext,
+            readOnly: opts.readOnly,
+            broker: opts.broker,
+            memory: opts.memory,
+            signal: opts.signal,
+            onText: opts.onText,
+            onToolCall,
+            onToolEvent,
+        });
+        const execUsage = accumulateUsage(emptyUsage(), routed.model, result.usage);
+        phases.push(phaseStat("execute", round, execStart, routed.model, execUsage));
+        usage = mergeUsage(usage, execUsage);
+        history = result.messages;
+        lastText = result.text;
+        totalSteps += result.steps;
+        // ── 5. JUDGE ──
+        const judgeStart = Date.now();
+        const verdict = await judgeCompleteness({
+            request: opts.prompt,
+            response: result.text,
+            filesTouched: [...filesTouched],
+            commandsRun,
+            steps: result.steps,
+            executorModel: routed.model,
+            signal: opts.signal,
+        });
+        phases.push(phaseStat("judge", round, judgeStart, verdict.model, verdict.usage));
+        usage = mergeUsage(usage, verdict.usage);
+        judgeRounds.push(verdict);
+        opts.onStage?.({
+            kind: "judge",
+            label: verdict.complete
+                ? `judged complete · ${verdict.confidence}% confident`
+                : `judged INCOMPLETE · ${verdict.findings.length} gap(s)`,
+            detail: `advisor: ${verdict.model.split("/").pop()}${verdict.fallback ? " (heuristic)" : ""}`,
+        });
+        const canRevise = !verdict.complete &&
+            round < maxRounds &&
+            !opts.readOnly &&
+            !opts.signal?.aborted;
+        if (!canRevise)
+            break;
+        prompt = buildRevisionPrompt(verdict);
+    }
+    const finalComplete = judgeRounds[judgeRounds.length - 1]?.complete ?? true;
+    opts.onStage?.({
+        kind: "complete",
+        label: finalComplete ? "turn complete" : "turn finished (gaps remain)",
+    });
+    const trace = assembleTrace({
+        cwd,
+        originalPrompt: opts.prompt,
+        evaluation,
+        enhancement,
+        routed,
+        response: lastText,
+        filesTouched: [...filesTouched],
+        commandsRun,
+        judgeRounds,
+        finalComplete,
+        steps: totalSteps,
+        usage,
+        startedAt,
+        verbose: opts.verbose,
+        phases,
+        toolEvents,
+    });
+    recordLesson(opts.fleetMemory, trace);
+    return {
+        text: lastText,
+        steps: totalSteps,
+        messages: history,
+        usage: { inputTokens: usage.inputTokens, outputTokens: usage.outputTokens },
+        trace,
+    };
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+function mergeUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        costUsd: a.costUsd + b.costUsd,
+    };
+}
+/** Build a {@link PhaseStat} from a start time (end is `now`) + its model/usage. */
+function phaseStat(phase, round, startedAt, model, usage) {
+    const finishedAt = Date.now();
+    return { phase, round, startedAt, finishedAt, durationMs: finishedAt - startedAt, model, usage };
+}
+function enhancementSource(resolved, lessons) {
+    if (resolved && lessons)
+        return "code-graph+memory";
+    if (resolved)
+        return "code-graph";
+    if (lessons)
+        return "memory";
+    return "none";
+}
+/**
+ * Pick the executor (worker) model. A manual pin always wins. Otherwise the Haiku
+ * evaluator is the authority — it already chose the cheapest tier that does the job
+ * well. The deterministic router is consulted only as a one-way SAFETY FLOOR: a
+ * high-stakes domain (auth/billing/security/migration/architecture) is never run
+ * below the precise tier even if the cheap evaluator under-rated it. We never
+ * downgrade the evaluator — leaning cheapest-for-quality is precisely its job.
+ */
+function selectModel(override, evaluation) {
+    if (override) {
+        return { model: override, tier: tierForSlug(override), rationale: "pinned model" };
+    }
+    let tier = evaluation.recommendedTier;
+    let rationale = `evaluator chose ${tierLabel(tier)} — cheapest tier for the job (complexity ${evaluation.complexity}/100)`;
+    // One-way safety floor: never under-spend on a high-stakes domain. classifyTier
+    // on text alone only returns "precise" for the auth/billing/security/migration
+    // domains, so this raises — never lowers — the evaluator's choice.
+    const floor = classifyTier({ text: evaluation.refinedPrompt });
+    if (floor.tier === "precise" && TIER_RANK[tier] < TIER_RANK.precise) {
+        tier = "precise";
+        rationale = `safety floor raised to ${tierLabel(tier)} — ${floor.rationale}`;
+    }
+    return { model: modelForTier(tier), tier, rationale };
+}
+function assembleTrace(a) {
+    return {
+        id: newTraceId(),
+        createdAt: a.startedAt,
+        cwd: a.cwd,
+        originalPrompt: a.originalPrompt,
+        evaluation: { ...a.evaluation, refinedPrompt: truncate(a.evaluation.refinedPrompt, 4000) },
+        enhancement: {
+            ...a.enhancement,
+            prompt: truncate(a.enhancement.prompt, 8000),
+            context: truncate(a.enhancement.context, 8000),
+        },
+        selectedModel: a.routed.model,
+        selectedTier: a.routed.tier,
+        selectionRationale: a.routed.rationale,
+        response: truncate(a.response, 4000),
+        filesTouched: a.filesTouched,
+        commandsRun: a.commandsRun,
+        judgeRounds: a.judgeRounds.map((v) => ({ ...v, reasoning: truncate(v.reasoning, 2000) })),
+        finalComplete: a.finalComplete,
+        steps: a.steps,
+        usage: a.usage,
+        durationMs: Date.now() - a.startedAt,
+        // Verbose telemetry — only attached when the turn ran in verbose mode, so
+        // non-verbose traces stay small. Tool events are capped to bound the file.
+        ...(a.verbose
+            ? {
+                verbose: true,
+                phases: a.phases,
+                toolEvents: (a.toolEvents ?? []).slice(-200),
+            }
+            : {}),
+    };
+}
+/**
+ * Record a weighted lesson when a turn revealed something worth remembering:
+ * the judge had to send the agent back (a gotcha) or it touched files (a routine
+ * change). Best-effort and silent — memory must never break a turn.
+ */
+function recordLesson(memory, trace) {
+    if (!memory)
+        return;
+    const needsRevision = trace.judgeRounds.length > 1;
+    if (!needsRevision && trace.filesTouched.length === 0)
+        return;
+    const firstVerdict = trace.judgeRounds[0];
+    if (needsRevision && firstVerdict && firstVerdict.findings.length > 0) {
+        memory.record({
+            kind: "gotcha",
+            weight: "high",
+            lesson: `Work for "${truncate(trace.originalPrompt, 80)}" was first judged incomplete: ` +
+                truncate(firstVerdict.findings.join("; "), 200),
+            files: trace.filesTouched.slice(0, 5),
+            outcome: trace.finalComplete ? "success" : "failure",
+        });
+    }
+    else if (trace.filesTouched.length > 0) {
+        memory.record({
+            kind: "routine-change",
+            weight: "low",
+            lesson: `Changed ${trace.filesTouched.slice(0, 5).join(", ")} for "${truncate(trace.originalPrompt, 80)}".`,
+            files: trace.filesTouched.slice(0, 5),
+            outcome: trace.finalComplete ? "success" : "failure",
+        });
+    }
+}
+/** Bare execution path: no eval/enhance/judge, but still traced for `/replay`. */
+async function runBare(opts, cwd, startedAt, filesTouched, commandsRun, onToolCall, onToolEvent, toolEvents) {
+    const model = opts.model ?? modelForTier("balanced");
+    opts.onStage?.({ kind: "execute", label: "executing (pipeline off)" });
+    const execStart = Date.now();
+    const result = await runAgent({
+        prompt: opts.prompt,
+        history: opts.history,
+        cwd,
+        model: opts.model,
+        maxSteps: opts.maxSteps,
+        projectContext: opts.projectContext,
+        readOnly: opts.readOnly,
+        broker: opts.broker,
+        memory: opts.memory,
+        signal: opts.signal,
+        onText: opts.onText,
+        onToolCall,
+        onToolEvent,
+    });
+    const usage = accumulateUsage(emptyUsage(), model, result.usage);
+    const phases = [phaseStat("execute", 0, execStart, model, usage)];
+    const evaluation = {
+        completeness: 0,
+        complexity: 0,
+        recommendedTier: tierForSlug(model),
+        missing: [],
+        contextQueries: [],
+        refinedPrompt: opts.prompt,
+        removed: [],
+        reasoning: "Pipeline disabled (bare mode).",
+        fallback: true,
+        model,
+        usage: emptyUsage(),
+    };
+    const trace = assembleTrace({
+        cwd,
+        originalPrompt: opts.prompt,
+        evaluation,
+        enhancement: { prompt: opts.prompt, context: "", resolved: [], lessonCount: 0, source: "none" },
+        routed: { model, tier: tierForSlug(model), rationale: "bare mode (no routing)" },
+        response: result.text,
+        filesTouched: [...filesTouched],
+        commandsRun,
+        judgeRounds: [],
+        finalComplete: true,
+        steps: result.steps,
+        usage,
+        startedAt,
+        verbose: opts.verbose,
+        phases,
+        toolEvents,
+    });
+    return {
+        text: result.text,
+        steps: result.steps,
+        messages: result.messages,
+        usage: { inputTokens: result.usage.inputTokens, outputTokens: result.usage.outputTokens },
+        trace,
+    };
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/agent/pipeline.js.map

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

package/dist/agent/planner.d.ts

@@ -0,0 +1,19 @@
+import { type Plan } from "./fleet/types.js";
+import type { FleetMemory } from "./fleet/memory.js";
+import type { AgentDefinition } from "../agents/types.js";
+export interface PlanOptions {
+    goal: string;
+    cwd: string;
+    /** Override the planning model slug (otherwise a balanced-tier model). */
+    model?: string;
+    memory?: FleetMemory | null;
+    /** Roster of named agents the planner may assign tasks to. */
+    agents?: AgentDefinition[];
+    signal?: AbortSignal;
+}
+/**
+ * Produce an executable {@link Plan} from a goal. Throws
+ * {@link MissingGatewayKeyError} if no gateway key is configured.
+ */
+export declare function planTasks(opts: PlanOptions): Promise<Plan>;
+//# sourceMappingURL=planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/agent/planner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAA8B,KAAK,IAAI,EAAa,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAgD1D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuBD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgEhE"}

package/dist/agent/planner.js

@@ -0,0 +1,139 @@
+/**
+ * Task planner — turn a goal into an executable plan.
+ *
+ * Decomposes a high-level goal ("add rate limiting to the API and document it")
+ * into a small set of concrete, dependency-ordered tasks the fleet can run in
+ * parallel. Uses one structured-output model call; the goal is prompt-enhanced
+ * first so the planner sees the actual files/symbols involved and produces tasks
+ * that name real paths instead of guesses.
+ *
+ * Each task's tier is reconciled with the cost router: the model proposes a tier,
+ * but a task the router flags as high-stakes (auth/billing/security/migration) is
+ * always escalated, never under-spent.
+ */
+import { generateObject } from "ai";
+import { z } from "zod";
+import { enhancePrompt } from "./prompt-enhancer.js";
+import { classifyTier, modelForTier } from "./model-router.js";
+import { ensureGatewayKey, MissingGatewayKeyError } from "./env.js";
+import { emptyUsage } from "./fleet/types.js";
+const TIER_RANK = { fast: 0, balanced: 1, precise: 2 };
+/** The more capable of two tiers (never under-spend on a risky task). */
+function maxTier(a, b) {
+    return TIER_RANK[a] >= TIER_RANK[b] ? a : b;
+}
+const planSchema = z.object({
+    tasks: z
+        .array(z.object({
+        id: z
+            .string()
+            .describe("Short kebab-case id, unique within the plan (e.g. 'add-route')."),
+        title: z.string().describe("Imperative one-line title."),
+        description: z
+            .string()
+            .describe("Self-contained instructions for an agent that has the repo but not this plan: " +
+            "what to change, in which files, and how to verify."),
+        dependsOn: z
+            .array(z.string())
+            .describe("ids of tasks that must finish first (empty if independent)."),
+        files: z
+            .array(z.string())
+            .describe("Relative paths this task will create or edit, as best you can predict."),
+        tier: z
+            .enum(["fast", "balanced", "precise"])
+            .describe("Model tier: 'fast' for mechanical/single-file, 'balanced' for normal feature work, " +
+            "'precise' for auth/billing/security/migrations/architecture."),
+        agent: z
+            .string()
+            .optional()
+            .describe("Name of a specialized agent from the roster to handle this task, when one clearly " +
+            "fits. Omit to use the general-purpose agent."),
+    }))
+        .min(1)
+        .max(20),
+});
+let planCounter = 0;
+function newPlanId() {
+    planCounter = (planCounter + 1) % 1_000_000;
+    return `plan_${Date.now().toString(36)}_${planCounter.toString(36)}`;
+}
+const PLANNER_SYSTEM = [
+    "You are the planning stage of an agentic coding system. Decompose the user's goal",
+    "into the SMALLEST set of concrete, independently-runnable tasks that fully achieve it.",
+    "",
+    "Rules:",
+    "- Prefer few, substantial tasks over many trivial ones. A one-file change is one task.",
+    "- Make tasks parallel where possible; only add a dependency when one task's output is",
+    "  genuinely required by another (e.g. a contract must exist before a route uses it).",
+    "- Predict the files each task touches; tasks that edit the same file should depend in",
+    "  sequence rather than run concurrently.",
+    "- Assign the cheapest sufficient tier per task; reserve 'precise' for auth, billing,",
+    "  security, migrations, schema, or architectural changes.",
+    "- Every task description must stand alone — the executing agent sees only its own task.",
+].join("\n");
+/**
+ * Produce an executable {@link Plan} from a goal. Throws
+ * {@link MissingGatewayKeyError} if no gateway key is configured.
+ */
+export async function planTasks(opts) {
+    const cwd = opts.cwd;
+    if (!ensureGatewayKey(cwd))
+        throw new MissingGatewayKeyError();
+    // Enhance the goal so the planner sees the real code involved.
+    const enhanced = await enhancePrompt({ prompt: opts.goal, cwd, memory: opts.memory });
+    const roster = new Set((opts.agents ?? []).map((a) => a.name));
+    const rosterBlock = opts.agents && opts.agents.length > 0
+        ? `\n\nAvailable specialized agents (assign a task's "agent" to one when it clearly fits):\n` +
+            opts.agents.map((a) => `- ${a.name}: ${a.description}`).join("\n")
+        : "";
+    const model = opts.model ?? modelForTier("balanced");
+    const { object } = await generateObject({
+        model,
+        schema: planSchema,
+        system: PLANNER_SYSTEM,
+        prompt: `Goal:\n${enhanced.prompt}${rosterBlock}`,
+        abortSignal: opts.signal,
+    });
+    const now = Date.now();
+    const seen = new Set();
+    const tasks = object.tasks.map((t, i) => {
+        // Guarantee unique, non-empty ids even if the model repeats or omits them.
+        let id = (t.id || `task-${i + 1}`).trim();
+        if (seen.has(id))
+            id = `${id}-${i + 1}`;
+        seen.add(id);
+        // Reconcile the proposed tier with the router's read of the description.
+        const routed = classifyTier({
+            text: `${t.title} ${t.description}`,
+            fileCount: t.files.length,
+        }).tier;
+        const tier = maxTier(t.tier, routed);
+        // Keep an agent assignment only if it names a real agent in the roster.
+        const agent = t.agent && roster.has(t.agent) ? t.agent : undefined;
+        return {
+            id,
+            title: t.title,
+            description: t.description,
+            status: "queued",
+            dependsOn: t.dependsOn ?? [],
+            files: t.files ?? [],
+            tier,
+            model: modelForTier(tier),
+            agent,
+            createdAt: now,
+            usage: emptyUsage(),
+        };
+    });
+    // Drop dependencies that point at ids no task actually has (model hallucination).
+    const ids = new Set(tasks.map((t) => t.id));
+    for (const t of tasks)
+        t.dependsOn = t.dependsOn.filter((d) => ids.has(d) && d !== t.id);
+    return {
+        id: newPlanId(),
+        goal: opts.goal,
+        createdAt: now,
+        tasks,
+        status: "draft",
+    };
+}
+//# sourceMappingURL=planner.js.map

package/dist/agent/planner.js.map

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

package/dist/agent/project-context.d.ts

@@ -0,0 +1,13 @@
+export interface ProjectContext {
+    /** Concatenated rule text, ready to drop into the system prompt. */
+    text: string;
+    /** Source files that contributed, relative to cwd. */
+    sources: string[];
+}
+/**
+ * Collect project rules by walking up from `cwd`. Nearest directory wins on
+ * ordering (its rules appear first), repo-root rules appear last. Total size is
+ * capped; once the cap is hit, remaining files are skipped.
+ */
+export declare function loadProjectContext(cwd: string): ProjectContext;
+//# sourceMappingURL=project-context.d.ts.map

package/dist/agent/project-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-context.d.ts","sourceRoot":"","sources":["../../src/agent/project-context.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAmC9D"}

package/dist/agent/project-context.js

@@ -0,0 +1,66 @@
+/**
+ * Project rules / instructions loading.
+ *
+ * Parity with Claude Code's `CLAUDE.md`: on session start we collect the
+ * project's standing instructions from well-known files, walking up from the
+ * working directory so nested rules and repo-root rules both apply. The result
+ * is injected once into the (stable) system prompt — it does not change per
+ * turn, which keeps the provider prompt cache warm.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, parse as parsePath, relative } from "node:path";
+/** Files we treat as project instructions, in priority order within a directory. */
+const RULE_FILES = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".oxagen/rules.md",
+    ".cursorrules",
+    ".github/copilot-instructions.md",
+];
+const MAX_TOTAL = 16_000; // chars; keep rules from dominating the context window
+const MAX_DEPTH = 8; // directories to walk up
+/**
+ * Collect project rules by walking up from `cwd`. Nearest directory wins on
+ * ordering (its rules appear first), repo-root rules appear last. Total size is
+ * capped; once the cap is hit, remaining files are skipped.
+ */
+export function loadProjectContext(cwd) {
+    const chunks = [];
+    const sources = [];
+    let total = 0;
+    let dir = cwd;
+    const { root } = parsePath(cwd);
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+        for (const rel of RULE_FILES) {
+            const full = join(dir, rel);
+            if (!existsSync(full))
+                continue;
+            let text;
+            try {
+                text = readFileSync(full, "utf8").trim();
+            }
+            catch {
+                continue;
+            }
+            if (!text)
+                continue;
+            const remaining = MAX_TOTAL - total;
+            if (remaining <= 0)
+                break;
+            const clipped = text.length > remaining
+                ? text.slice(0, remaining) + "\n… [rules truncated]"
+                : text;
+            const source = relative(cwd, full) || rel;
+            chunks.push(`### ${source}\n${clipped}`);
+            sources.push(source);
+            total += clipped.length;
+        }
+        if (total >= MAX_TOTAL)
+            break;
+        if (dir === root)
+            break;
+        dir = dirname(dir);
+    }
+    return { text: chunks.join("\n\n"), sources };
+}
+//# sourceMappingURL=project-context.js.map

package/dist/agent/project-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-context.js","sourceRoot":"","sources":["../../src/agent/project-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,IAAI,SAAS,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAExE,oFAAoF;AACpF,MAAM,UAAU,GAAG;IACjB,WAAW;IACX,WAAW;IACX,kBAAkB;IAClB,cAAc;IACd,iCAAiC;CAClC,CAAC;AAEF,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,uDAAuD;AACjF,MAAM,SAAS,GAAG,CAAC,CAAC,CAAC,yBAAyB;AAS9C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,IAAI,GAAG,GAAG,GAAG,CAAC;IACd,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAChC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;gBAAE,SAAS;YAChC,IAAI,IAAY,CAAC;YACjB,IAAI,CAAC;gBACH,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YAC3C,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,MAAM,SAAS,GAAG,SAAS,GAAG,KAAK,CAAC;YACpC,IAAI,SAAS,IAAI,CAAC;gBAAE,MAAM;YAC1B,MAAM,OAAO,GACX,IAAI,CAAC,MAAM,GAAG,SAAS;gBACrB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,uBAAuB;gBACpD,CAAC,CAAC,IAAI,CAAC;YACX,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,GAAG,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,MAAM,KAAK,OAAO,EAAE,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;QAC1B,CAAC;QACD,IAAI,KAAK,IAAI,SAAS;YAAE,MAAM;QAC9B,IAAI,GAAG,KAAK,IAAI;YAAE,MAAM;QACxB,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC"}