@cruxy/cli 0.1.0

package/dist/agent/prompts.js

@@ -0,0 +1,99 @@
+/**
+ * cruxy-code agent prompts.
+ *
+ * These are ORIGINAL prompts written for cruxy — not copied from any other
+ * tool. The system prompt is assembled at runtime from a static core plus a
+ * dynamic environment block, so the model always knows where it is, what it
+ * can do, and how it's expected to behave.
+ */
+/**
+ * The static core of cruxy's behaviour. Phrased as direct instruction to the
+ * model. Keep this tight — every line earns its place; vague prose dilutes the
+ * signal the model actually follows.
+ */
+const CORE = `You are cruxy, an agentic coding assistant working through a command-line interface on a real codebase. You complete software tasks by reading code, editing files, and running commands via the tools provided — you do not just describe what to do, you do it.
+
+## Operating loop
+Work in a tight loop: gather context, then act, then verify. Concretely:
+1. Understand the request and the relevant code before changing anything. Read the files you intend to touch; never edit a file you haven't read this session.
+2. For non-trivial tasks, form a short plan and follow it. Prefer the smallest change that fully solves the problem.
+3. Make the change with the editing tools. Ground every edit in exact text: edit_file's old_str must be copied verbatim from what you read, never paraphrased from the user's description. If the text the user described doesn't appear in the file, do not edit — show the closest actual match and ask.
+4. Verify your work — run the build, tests, type-checker, or linter when they exist. Treat a task as done only when it actually works, not when the edit is written.
+5. If verification fails, read the error, fix the cause, and re-verify. Iterate. Do not loop blindly on the same failing approach; if two attempts fail, step back and reconsider.
+
+## Editing discipline
+- Match the surrounding code's style, naming, and patterns. The goal is a change that looks like it was always there.
+- Make minimal, targeted edits. Do not reformat unrelated code or "drive-by" refactor.
+- Never leave placeholder stubs, TODOs, or "// implement later" in place of real work unless the user asked for a scaffold.
+- Do not invent APIs, functions, libraries, or file paths. If you're unsure something exists, check before relying on it.
+- Don't add comments that merely restate the code. Add a comment only where intent is genuinely non-obvious.
+- Prefer existing utilities and dependencies over adding new ones. Flag any new dependency before introducing it.
+- Prefer the dedicated file tools — read_file, write_file, edit_file — over shelling out to cat or sed to read or edit files.
+- For changes spanning multiple files or multiple hunks, prefer apply_patch — one reviewed approval, applied atomically (all-or-nothing) — over a series of edit_file calls. A single tiny edit can still use edit_file.
+- To find where something is defined or used, search file contents with grep_files, not run_command with grep or find.
+
+## Running commands
+- Explain a command's effect before running it when the effect isn't obvious.
+- Be careful with anything destructive or irreversible (deleting files, force-pushing, dropping data, mass find-replace, rm -rf). ${"${APPROVAL_CLAUSE}"}
+- Never run commands that exfiltrate secrets, weaken security, or touch systems outside the working tree without an explicit instruction to do so.
+- Read command output. Don't claim success you haven't observed. Never describe an edit a tool didn't actually perform; if an action was denied or made no change, say so plainly.
+
+## Communication
+- Be concise and direct. Skip preamble and filler. Lead with the result, not a recap of the request.
+- When you finish, briefly state what you changed and how you verified it. Reference file paths and the commands you ran.
+- Surface real uncertainty and trade-offs honestly; don't paper over them. If a request is ambiguous in a way that changes the outcome, ask one focused question rather than guessing.
+- Don't claim a task is complete if it isn't. "Mostly working" is not done.
+
+## Boundaries
+- Stay within the working directory and the task at hand.
+- If a request would require destructive or out-of-scope action, surface that and confirm intent before proceeding.
+- You operate on the user's machine and their code — act with the care you'd want from a careful colleague.`;
+function renderEnvironment(ctx) {
+    const lines = [
+        `- Working directory: ${ctx.cwd}`,
+        `- Platform: ${ctx.platform}`,
+        `- Date: ${ctx.date}`,
+        `- Model: ${ctx.model}`,
+    ];
+    if (ctx.git) {
+        lines.push(`- Git: branch ${ctx.git.branch}${ctx.git.dirty ? " (uncommitted changes present)" : " (clean)"}`);
+    }
+    return `## Environment\n${lines.join("\n")}`;
+}
+function renderTools(tools) {
+    if (tools.length === 0) {
+        return "## Tools\nNo tools are available this session; respond in text only.";
+    }
+    const list = tools.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+    return `## Tools\nYou have these tools available. Use them — don't ask the user to run things you can run yourself:\n${list}`;
+}
+/** Assemble the full system prompt for a session. */
+export function buildSystemPrompt(ctx) {
+    const approval = ctx.autoApprove
+        ? "Auto-approve is on for this session, so you may proceed without asking — but still pause and confirm before genuinely destructive or irreversible actions."
+        : "Confirm with the user before taking any destructive or irreversible action.";
+    const core = CORE.replace("${APPROVAL_CLAUSE}", approval);
+    const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
+    if (ctx.projectInstructions?.trim()) {
+        sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Compact reminder injected after tool results when the loop has run long, to
+ * keep the model anchored to the original objective and the verify step.
+ */
+export const PROGRESS_REMINDER = `Reminder: stay focused on the original task. Before declaring done, verify your change actually works (build/tests/lint), then summarize what changed.`;
+/**
+ * System prompt for the side conversation that compacts an over-long history
+ * (see Session.compact). It runs as a standalone, tool-less completion over a
+ * rendered transcript — the goal is a synopsis dense enough that the main loop
+ * can continue without the verbatim prefix.
+ */
+export const SUMMARY_SYSTEM = `You are compacting a coding assistant's conversation to fit within its context window. Summarize the conversation so far into a compact synopsis that preserves: decisions made and their rationale, concrete file paths and identifiers touched, the current state of the work, and any open or pending tasks. Be specific and terse — omit pleasantries and restated instructions. Output only the synopsis.`;
+/**
+ * Marker embedded in the synthetic messages that replace a compacted prefix, so
+ * they're recognizable in the history (and fold cleanly into a later
+ * re-summarization rather than being mistaken for live conversation).
+ */
+export const COMPACTION_MARKER = "[conversation compacted]";

package/dist/agent/session.d.ts

@@ -0,0 +1,107 @@
+import type { Message, Provider, Usage } from "@cruxy/sdk";
+import type { CruxyConfig } from "../config/index.js";
+import type { ToolContext } from "../tools/index.js";
+import type { ToolRegistry } from "../tools/index.js";
+import { type AgentResult } from "./loop.js";
+export interface SessionArgs {
+    /** A constructed provider to stream from. */
+    provider: Provider;
+    /** The tool catalogue advertised to the model and dispatched against. */
+    registry: ToolRegistry;
+    /** Resolved CLI configuration. */
+    config: CruxyConfig;
+    /** Ambient capabilities handed to each tool. */
+    ctx: ToolContext;
+    /** Git context (branch + dirty), loaded at startup, for the system prompt. */
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    /** Project instructions (e.g. CRUXY.md) folded into every turn's system prompt. */
+    projectInstructions?: string | null;
+}
+/**
+ * Estimate the token footprint of a message list with a cheap chars/4 heuristic
+ * — no tokenizer dependency. Good enough to decide *when* to compact; exact
+ * counts are deferred to a later phase. Counts only textual payload (block
+ * structure and role labels are negligible and ignored).
+ */
+export declare function estimateTokens(messages: Message[]): number;
+/**
+ * Owns the state of one multi-turn conversation: the running message history and
+ * the usage accumulated across turns. Each `send` continues from the prior
+ * history (tool_use/tool_result blocks included) rather than starting cold.
+ *
+ * This is also the home for context compaction: before each turn the running
+ * history is measured and, if it crosses the configured threshold, its older
+ * prefix is summarized away so the conversation stays within the model's window.
+ * The system prompt lives in `runAgent`, never in `messages`, so compaction
+ * cannot touch it.
+ */
+export declare class Session {
+    /** The full running conversation, replaced with the extended history each turn. */
+    messages: Message[];
+    /** Token usage summed across every `send` (and every compaction) in this session. */
+    readonly usage: Usage;
+    private readonly args;
+    /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
+    private projectInstructions;
+    constructor(args: SessionArgs);
+    /**
+     * Run one user turn: append the prompt, compact if the history has grown past
+     * the threshold, drive the agent loop over the full history, adopt the
+     * extended history, and accumulate usage. Returns the turn's `AgentResult`.
+     *
+     * `onText`, when supplied, receives assistant text deltas as they stream so the
+     * caller can render them live (see the REPL); history is unaffected.
+     */
+    send(userPrompt: string, onText?: (delta: string) => void): Promise<AgentResult>;
+    /**
+     * Re-read project instructions (CRUXY.md / AGENTS.md) from the working
+     * directory so edits take effect without restarting. Returns the new text, or
+     * `null` if none is present. Backs the `/reload` command.
+     */
+    reloadProjectInstructions(): string | null;
+    /** Drop the conversation history but keep the session (for `/clear`). */
+    clear(): void;
+    /**
+     * Compact only when the estimated history exceeds
+     * `compactThreshold * maxTokens`. On success logs a one-line notice and
+     * returns the number of older messages folded into the summary; otherwise
+     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     */
+    maybeCompact(): Promise<number | null>;
+    /**
+     * Force compaction regardless of the threshold (backs `/compact`). Returns the
+     * number of older messages summarized, or `null` if there was nothing safe to
+     * cut or the summary call failed.
+     */
+    compact(): Promise<number | null>;
+    /**
+     * Find a clean cut, summarize the older prefix into a synthetic user/assistant
+     * pair, and splice it in front of the kept-recent messages. Best-effort: a
+     * failed summary call leaves the history untouched and returns `null` (fail
+     * open — losing compaction is degraded, not unsafe).
+     */
+    private runCompaction;
+    /**
+     * Choose the boundary between the summarized prefix and the kept-recent tail.
+     *
+     * Tool-call integrity is the constraint: a `tool_use` (assistant) and its
+     * matching `tool_result` (the next user message) must never straddle the cut,
+     * or the next provider call breaks. A real user *prompt* (`role:"user"` with
+     * string content) only occurs at a completed turn boundary, where every prior
+     * tool exchange is already resolved — so the kept region must begin there.
+     *
+     * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
+     * such prompt: this keeps at least the recent floor and lands clean. Returns
+     * the cut index, or `null` if no safe boundary leaves a non-empty prefix
+     * (e.g. a single long in-progress turn — nothing safe to compact).
+     */
+    private findCut;
+    /**
+     * Summarize a prefix via a standalone, tool-less provider call over a rendered
+     * transcript. Throws on a stream error or empty output so callers fail open.
+     */
+    private summarize;
+}

package/dist/agent/session.js

@@ -0,0 +1,236 @@
+import { loadProjectInstructions } from "../config/index.js";
+import { runAgent } from "./loop.js";
+import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
+/**
+ * Estimate the token footprint of a message list with a cheap chars/4 heuristic
+ * — no tokenizer dependency. Good enough to decide *when* to compact; exact
+ * counts are deferred to a later phase. Counts only textual payload (block
+ * structure and role labels are negligible and ignored).
+ */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            chars += msg.content.length;
+            continue;
+        }
+        for (const block of msg.content) {
+            switch (block.type) {
+                case "text":
+                    chars += block.text.length;
+                    break;
+                case "tool_use":
+                    chars += block.name.length + JSON.stringify(block.input).length;
+                    break;
+                case "tool_result":
+                    chars += block.content.length;
+                    break;
+            }
+        }
+    }
+    return Math.ceil(chars / 4);
+}
+/**
+ * Owns the state of one multi-turn conversation: the running message history and
+ * the usage accumulated across turns. Each `send` continues from the prior
+ * history (tool_use/tool_result blocks included) rather than starting cold.
+ *
+ * This is also the home for context compaction: before each turn the running
+ * history is measured and, if it crosses the configured threshold, its older
+ * prefix is summarized away so the conversation stays within the model's window.
+ * The system prompt lives in `runAgent`, never in `messages`, so compaction
+ * cannot touch it.
+ */
+export class Session {
+    /** The full running conversation, replaced with the extended history each turn. */
+    messages = [];
+    /** Token usage summed across every `send` (and every compaction) in this session. */
+    usage = { input_tokens: 0, output_tokens: 0 };
+    args;
+    /** Mutable so `/reload` can refresh CRUXY.md mid-session. */
+    projectInstructions;
+    constructor(args) {
+        this.args = args;
+        this.projectInstructions = args.projectInstructions ?? null;
+    }
+    /**
+     * Run one user turn: append the prompt, compact if the history has grown past
+     * the threshold, drive the agent loop over the full history, adopt the
+     * extended history, and accumulate usage. Returns the turn's `AgentResult`.
+     *
+     * `onText`, when supplied, receives assistant text deltas as they stream so the
+     * caller can render them live (see the REPL); history is unaffected.
+     */
+    async send(userPrompt, onText) {
+        this.messages.push({ role: "user", content: userPrompt });
+        // Compact *before* the agent call so the turn runs against a bounded history.
+        await this.maybeCompact();
+        const result = await runAgent({
+            messages: this.messages,
+            ...this.args,
+            // After the spread so a mid-session `/reload` wins over the initial value.
+            projectInstructions: this.projectInstructions,
+            onText,
+        });
+        this.messages = result.messages;
+        this.usage.input_tokens += result.usage.input_tokens;
+        this.usage.output_tokens += result.usage.output_tokens;
+        return result;
+    }
+    /**
+     * Re-read project instructions (CRUXY.md / AGENTS.md) from the working
+     * directory so edits take effect without restarting. Returns the new text, or
+     * `null` if none is present. Backs the `/reload` command.
+     */
+    reloadProjectInstructions() {
+        this.projectInstructions = loadProjectInstructions(this.args.ctx.cwd);
+        return this.projectInstructions;
+    }
+    /** Drop the conversation history but keep the session (for `/clear`). */
+    clear() {
+        this.messages = [];
+    }
+    /**
+     * Compact only when the estimated history exceeds
+     * `compactThreshold * maxTokens`. On success logs a one-line notice and
+     * returns the number of older messages folded into the summary; otherwise
+     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     */
+    async maybeCompact() {
+        const { maxTokens, compactThreshold } = this.args.config.context;
+        if (estimateTokens(this.messages) <= compactThreshold * maxTokens) {
+            return null;
+        }
+        const n = await this.runCompaction();
+        if (n) {
+            this.args.ctx.logger.info(`compacted ${n} older message${n === 1 ? "" : "s"} to stay within context`);
+        }
+        return n;
+    }
+    /**
+     * Force compaction regardless of the threshold (backs `/compact`). Returns the
+     * number of older messages summarized, or `null` if there was nothing safe to
+     * cut or the summary call failed.
+     */
+    async compact() {
+        return this.runCompaction();
+    }
+    /**
+     * Find a clean cut, summarize the older prefix into a synthetic user/assistant
+     * pair, and splice it in front of the kept-recent messages. Best-effort: a
+     * failed summary call leaves the history untouched and returns `null` (fail
+     * open — losing compaction is degraded, not unsafe).
+     */
+    async runCompaction() {
+        const cut = this.findCut();
+        if (cut === null)
+            return null;
+        const prefix = this.messages.slice(0, cut);
+        const kept = this.messages.slice(cut);
+        let synopsis;
+        try {
+            const summary = await this.summarize(prefix);
+            synopsis = summary.text;
+            this.usage.input_tokens += summary.usage.input_tokens;
+            this.usage.output_tokens += summary.usage.output_tokens;
+        }
+        catch (err) {
+            this.args.ctx.logger.warn(`compaction skipped: summary failed (${err.message})`);
+            return null;
+        }
+        // A user/assistant pair, not a lone message: the kept region begins with a
+        // user prompt, so a single synthetic user message would put two user turns
+        // back-to-back and break provider alternation.
+        const summaryMessages = [
+            {
+                role: "user",
+                content: `${COMPACTION_MARKER} The earlier conversation was compacted to conserve context; a summary follows.`,
+            },
+            {
+                role: "assistant",
+                content: `${COMPACTION_MARKER} Summary of the conversation so far:\n\n${synopsis}`,
+            },
+        ];
+        this.messages = [...summaryMessages, ...kept];
+        return prefix.length;
+    }
+    /**
+     * Choose the boundary between the summarized prefix and the kept-recent tail.
+     *
+     * Tool-call integrity is the constraint: a `tool_use` (assistant) and its
+     * matching `tool_result` (the next user message) must never straddle the cut,
+     * or the next provider call breaks. A real user *prompt* (`role:"user"` with
+     * string content) only occurs at a completed turn boundary, where every prior
+     * tool exchange is already resolved — so the kept region must begin there.
+     *
+     * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
+     * such prompt: this keeps at least the recent floor and lands clean. Returns
+     * the cut index, or `null` if no safe boundary leaves a non-empty prefix
+     * (e.g. a single long in-progress turn — nothing safe to compact).
+     */
+    findCut() {
+        const { keepRecentMessages } = this.args.config.context;
+        const start = this.messages.length - keepRecentMessages;
+        for (let i = start; i >= 1; i--) {
+            const msg = this.messages[i];
+            if (msg.role === "user" && typeof msg.content === "string")
+                return i;
+        }
+        return null;
+    }
+    /**
+     * Summarize a prefix via a standalone, tool-less provider call over a rendered
+     * transcript. Throws on a stream error or empty output so callers fail open.
+     */
+    async summarize(prefix) {
+        const transcript = renderTranscript(prefix);
+        const usage = { input_tokens: 0, output_tokens: 0 };
+        let text = "";
+        for await (const ev of this.args.provider.stream({
+            system: SUMMARY_SYSTEM,
+            messages: [{ role: "user", content: transcript }],
+        })) {
+            switch (ev.type) {
+                case "text_delta":
+                    text += ev.text;
+                    break;
+                case "usage":
+                    usage.input_tokens = ev.usage.input_tokens || usage.input_tokens;
+                    usage.output_tokens += ev.usage.output_tokens;
+                    break;
+                case "error":
+                    throw ev.error;
+                default:
+                    break;
+            }
+        }
+        if (!text.trim())
+            throw new Error("summary was empty");
+        return { text: text.trim(), usage };
+    }
+}
+/** Render a message list to a compact plain-text transcript for summarization. */
+function renderTranscript(messages) {
+    const parts = [];
+    for (const msg of messages) {
+        const role = msg.role === "user" ? "User" : "Assistant";
+        parts.push(`${role}: ${renderContent(msg.content)}`);
+    }
+    return parts.join("\n\n");
+}
+function renderContent(content) {
+    if (typeof content === "string")
+        return content;
+    return content
+        .map((block) => {
+        switch (block.type) {
+            case "text":
+                return block.text;
+            case "tool_use":
+                return `[called ${block.name}(${JSON.stringify(block.input)})]`;
+            case "tool_result":
+                return `[tool result${block.is_error ? " (error)" : ""}: ${block.content}]`;
+        }
+    })
+        .join("\n");
+}

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function configCommand(): Command;

package/dist/cli/commands/config.js

@@ -0,0 +1,59 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { logger } from "../../utils/logger.js";
+import { loadConfig, getPath, setValue, initConfig, globalConfigPath, findProjectConfig, } from "../../config/index.js";
+export function configCommand() {
+    const cmd = new Command("config").description("manage cruxy configuration");
+    cmd
+        .command("list")
+        .alias("ls")
+        .description("print the fully-resolved configuration")
+        .action(() => {
+        const { config } = loadConfig();
+        logger.print(JSON.stringify(config, null, 2));
+    });
+    cmd
+        .command("get <key>")
+        .description("read a single value (dot-path, e.g. model.temperature)")
+        .action((key) => {
+        const { config } = loadConfig();
+        const value = getPath(config, key);
+        if (value === undefined) {
+            logger.error(`no such config key: ${pc.bold(key)}`);
+            process.exitCode = 1;
+            return;
+        }
+        logger.print(typeof value === "object"
+            ? JSON.stringify(value, null, 2)
+            : String(value));
+    });
+    cmd
+        .command("set <key> <value>")
+        .description("write a value to the config (dot-path)")
+        .option("-p, --project", "write to the project config instead of global")
+        .action((key, value, opts) => {
+        const file = opts.project
+            ? (findProjectConfig() ?? "cruxy.config.json")
+            : globalConfigPath();
+        const written = setValue(key, value, file);
+        logger.print(`${pc.green("set")} ${pc.bold(key)} = ${value}  ${pc.dim(`(${written})`)}`);
+    });
+    cmd
+        .command("path")
+        .description("show config file locations")
+        .action(() => {
+        const project = findProjectConfig();
+        logger.print(`${pc.bold("global:")}  ${globalConfigPath()}`);
+        logger.print(`${pc.bold("project:")} ${project ?? pc.dim("(none found)")}`);
+    });
+    cmd
+        .command("init")
+        .description("write a default global config file")
+        .action(() => {
+        const { path, created } = initConfig(globalConfigPath());
+        logger.print(created
+            ? `${pc.green("created")} ${path}`
+            : `${pc.yellow("exists")}  ${path} ${pc.dim("(left unchanged)")}`);
+    });
+    return cmd;
+}

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function runCommand(): Command;

package/dist/cli/commands/run.js

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { createProvider } from "@cruxy/sdk";
+import { logger } from "../../utils/logger.js";
+import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { buildDefaultRegistry } from "../../tools/index.js";
+import { Session, createApprover } from "../../agent/index.js";
+import { runInteractive } from "../repl.js";
+import { createStreamPrinter } from "../stream-print.js";
+import { getGitInfo } from "../../utils/git.js";
+export function runCommand() {
+    return new Command("run")
+        .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
+        .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
+        .option("-y, --yes", "auto-approve all tool actions (run unattended)")
+        .option("--dangerously-approve", "alias for --yes: approve every action without prompting")
+        .action(async (promptParts, opts) => {
+        const prompt = promptParts.join(" ").trim();
+        const interactive = prompt === "";
+        // No prompt and stdin isn't a terminal: there's no way to read input and
+        // nothing to do — fail fast instead of hanging on a line that never comes.
+        if (interactive && !process.stdin.isTTY) {
+            logger.error('cruxy run needs a prompt when stdin is not a terminal — try: cruxy run "<task>"');
+            return;
+        }
+        const { config, sources } = loadConfig();
+        const apiKey = resolveApiKey(config.model.provider);
+        logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
+        logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        if (!apiKey) {
+            logger.warn(`no API key for provider ${pc.bold(config.model.provider)} — set it in the environment before running.`);
+            return;
+        }
+        const provider = createProvider({
+            provider: config.model.provider,
+            apiKey,
+            model: config.model.model,
+            maxTokens: config.model.maxTokens,
+            temperature: config.model.temperature,
+            gatewayUrl: config.cruxy.gatewayUrl,
+        });
+        const registry = buildDefaultRegistry();
+        const approver = createApprover({
+            mode: config.approval.mode,
+            cwd: process.cwd(),
+            isInteractive: Boolean(process.stdin.isTTY),
+            autoApprove: Boolean(opts.yes || opts.dangerouslyApprove),
+            logger,
+        });
+        const ctx = {
+            cwd: process.cwd(),
+            config,
+            logger,
+            approve: (action) => approver.approve(action),
+        };
+        const projectInstructions = loadProjectInstructions(process.cwd());
+        const git = getGitInfo(process.cwd());
+        const session = new Session({
+            provider,
+            registry,
+            config,
+            ctx,
+            git,
+            projectInstructions,
+        });
+        if (interactive) {
+            await runInteractive(session);
+            return;
+        }
+        // One-shot: a single turn, then exit. Preserves scripting/pipe use.
+        // Assistant text streams to stdout delta by delta (same as the REPL),
+        // through a printer that trims the model's leading blank lines; the agent
+        // loop terminates the line.
+        logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
+        try {
+            const print = createStreamPrinter((text) => process.stdout.write(text));
+            const result = await session.send(prompt, print);
+            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+        }
+        catch (err) {
+            logger.error(err.message);
+        }
+    });
+}

package/dist/cli/program.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function buildProgram(): Command;

package/dist/cli/program.js

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
+import { logger } from "../utils/logger.js";
+import { runCommand } from "./commands/run.js";
+import { configCommand } from "./commands/config.js";
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name(APP_NAME)
+        .description(`cruxy-code — ${APP_DESCRIPTION}`)
+        .version(APP_VERSION, "-v, --version", "print the cruxy version")
+        .option("-c, --config <path>", "use a specific config file")
+        .option("--log-level <level>", "debug | info | warn | error | silent")
+        .option("--verbose", "shorthand for --log-level debug")
+        .showHelpAfterError("(run `cruxy --help` for usage)");
+    // Apply global options as early as possible.
+    program.hook("preAction", (thisCommand) => {
+        const opts = thisCommand.opts();
+        if (opts.verbose)
+            logger.setLevel("debug");
+        else if (opts.logLevel)
+            logger.setLevel(opts.logLevel);
+    });
+    program.addCommand(runCommand());
+    program.addCommand(configCommand());
+    // Default action: no subcommand -> interactive entrypoint (stub for now).
+    program.action(() => {
+        logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
+        logger.print(pc.dim("an agentic coding CLI\n"));
+        logger.print("The interactive REPL lands in C.3 (terminal UI).");
+        logger.print(`For now try:  ${pc.bold('cruxy run "<task>"')}  or  ${pc.bold("cruxy config path")}`);
+        logger.print(`See all commands:  ${pc.bold("cruxy --help")}`);
+    });
+    return program;
+}

package/dist/cli/repl.d.ts

@@ -0,0 +1,15 @@
+import type { Readable, Writable } from "node:stream";
+import type { Session } from "../agent/index.js";
+/** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
+export interface ReplIO {
+    input: Readable;
+    output: Writable;
+}
+/**
+ * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
+ * commands or run a turn, repeat. Assistant text streams to stdout from within
+ * `session.send` (via the logger); this loop only owns input and control.
+ *
+ * `io` defaults to real stdin/stdout; tests inject a scripted stream pair.
+ */
+export declare function runInteractive(session: Session, io?: ReplIO): Promise<void>;