@cruxy/cli 0.7.0 → 0.9.0

package/dist/render/tty-renderer.js

@@ -0,0 +1,276 @@
+import pc from "picocolors";
+import { createStreamPrinter } from "../cli/stream-print.js";
+import { renderActionPreview } from "./diff.js";
+import { createStreamHighlighter, } from "./highlight.js";
+import { composeStatusLine, ELAPSED_AFTER_MS, formatElapsed, phaseIdentity, } from "./state.js";
+/** Erase the current line and return the cursor to column 0. */
+const CLEAR_LINE = "\r\x1b[2K";
+/** Spinner frames (braille); a static glyph when animation is disabled. */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const STATIC_FRAME = "◐";
+const SPINNER_INTERVAL_MS = 100;
+/**
+ * The interactive renderer: committed content is append-only; the one transient
+ * thing on screen is a single managed status line, redrawn in place.
+ *
+ * The no-flicker discipline, concretely:
+ * - Only the status line is ever rewritten, via `\r` + erase-line — never a
+ *   screen clear, never a repaint of committed rows.
+ * - Every committed write first erases the status line, so the live region is
+ *   always the last row and committed text can never interleave with it. A
+ *   committed write *dismisses* the status (it does not redraw underneath), so
+ *   nothing re-renders per delta while text streams.
+ * - The status text is hard-truncated to the terminal width: a soft-wrapped
+ *   status would span two rows and erase-line could no longer clean it up.
+ *
+ * Fenced code blocks are highlighted incrementally (see highlight.ts): prose
+ * deltas pass straight through, code is styled line-by-line on arrival.
+ *
+ * U.4 layers semantic state onto the SAME single live line — no new screen
+ * real estate, no extra timers. Two registers compose into it:
+ * - `phase` (loop-owned; cleared by endTurn) — thinking / calling-tool / …
+ * - `progressState` (plan-executor-owned; cleared only via progress(null))
+ * A committed write still only *hides* the drawn line (registers survive);
+ * the next state transition redraws. Nothing redraws per streamed delta, so
+ * the U.2 first-chunk-immediate guarantee is untouched.
+ */
+export class TtyRenderer {
+    caps;
+    out;
+    colors;
+    print;
+    highlighter;
+    wroteInSegment = false;
+    /** Ad-hoc/legacy status text; wins over composed state when set. */
+    rawStatus = null;
+    phase = null;
+    progressState = null;
+    /** When the current phase *identity* began — drives honest elapsed display. */
+    phaseStartedAt = 0;
+    /** In-flight tool call (serial by contract) for end-note duration. */
+    toolStart = null;
+    /** Phase (+ its clock) displaced by an approval prompt, for promptResolved. */
+    displaced = null;
+    /** Whether the live line is currently drawn on screen. */
+    lineVisible = false;
+    timer = null;
+    frame = 0;
+    closed = false;
+    constructor(caps, out) {
+        this.caps = caps;
+        this.out = out;
+        this.colors = pc.createColors(caps.color);
+        this.highlighter = createStreamHighlighter(this.colors);
+        this.print = this.newPrinter();
+    }
+    newPrinter() {
+        return createStreamPrinter((text) => {
+            this.commit(this.highlighter.push(text));
+        });
+    }
+    /** Append committed content, erasing the status line first if one is live. */
+    commit(text) {
+        if (text === "")
+            return;
+        // Legacy ad-hoc status is decor and dies with the dismissal (U.2
+        // semantics); the typed U.4 registers survive for the next transition.
+        this.rawStatus = null;
+        this.hideLine();
+        this.wroteInSegment = true;
+        this.out.write(text);
+    }
+    /**
+     * Erase the drawn live line and stop the spinner — WITHOUT clearing the
+     * state registers. Committed content takes the screen; the next state
+     * transition redraws with full context. (This is what keeps streaming
+     * zero-cost: no redraw-under per delta.)
+     */
+    hideLine() {
+        if (!this.lineVisible)
+            return;
+        this.lineVisible = false;
+        this.stopTimer();
+        this.out.write(CLEAR_LINE);
+    }
+    stopTimer() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * The current live-line text, composed from the registers. `null` means the
+     * line must be hidden: nothing to say, or an interactive prompt owns the
+     * terminal (`awaiting-approval` — two things can't share the last row).
+     */
+    currentLine() {
+        if (this.rawStatus !== null)
+            return this.rawStatus;
+        if (this.phase?.kind === "awaiting-approval")
+            return null;
+        if (this.phase === null && this.progressState === null)
+            return null;
+        // Elapsed only when it can keep ticking honestly: the spinner timer is the
+        // only thing that redraws between transitions, so no spinner → no number.
+        const elapsed = this.phase !== null && this.caps.spinner
+            ? Date.now() - this.phaseStartedAt
+            : undefined;
+        return composeStatusLine(this.progressState, this.phase, elapsed);
+    }
+    /** Redraw the live line from current state, or hide it when there is none. */
+    refresh() {
+        const line = this.currentLine();
+        if (line === null) {
+            this.hideLine();
+            return;
+        }
+        this.drawLine(line);
+        if (this.caps.spinner && this.timer === null) {
+            this.timer = setInterval(() => {
+                this.frame++;
+                const current = this.currentLine();
+                if (current !== null)
+                    this.drawLine(current);
+            }, SPINNER_INTERVAL_MS);
+            // Never hold the process open for a spinner.
+            this.timer.unref?.();
+        }
+    }
+    drawLine(text) {
+        this.lineVisible = true;
+        const glyph = this.caps.spinner
+            ? FRAMES[this.frame % FRAMES.length]
+            : STATIC_FRAME;
+        // Reserve glyph + space; truncate so the live line can never soft-wrap.
+        const room = Math.max(1, this.caps.width - 2);
+        const line = text.length > room ? text.slice(0, Math.max(0, room - 1)) + "…" : text;
+        this.out.write(`${CLEAR_LINE}${this.colors.cyan(glyph)} ${this.colors.dim(line)}`);
+    }
+    beginTurn() {
+        this.highlighter = createStreamHighlighter(this.colors);
+        this.print = this.newPrinter();
+        this.wroteInSegment = false;
+    }
+    write(delta) {
+        if (this.closed)
+            return;
+        this.print(delta);
+    }
+    endSegment() {
+        if (this.closed)
+            return;
+        this.commit(this.highlighter.flush());
+        if (this.wroteInSegment) {
+            this.commit("\n");
+            this.wroteInSegment = false;
+        }
+    }
+    note(text) {
+        if (this.closed)
+            return;
+        const room = Math.max(1, this.caps.width);
+        const line = text.length > room ? text.slice(0, room - 1) + "…" : text;
+        this.commit(this.colors.dim(line) + "\n");
+    }
+    preview(preview) {
+        if (this.closed)
+            return;
+        const block = renderActionPreview(preview, this.colors);
+        if (block)
+            this.commit(block + "\n");
+    }
+    status(text) {
+        if (this.closed)
+            return;
+        this.rawStatus = text;
+        if (text === null) {
+            // Legacy clear semantics: hide now, redraw only on the next transition.
+            this.hideLine();
+            return;
+        }
+        this.refresh();
+    }
+    setPhase(phase) {
+        if (this.closed)
+            return;
+        // Entering awaiting-approval stashes what it displaces (phase + clock) so
+        // promptResolved can put the world back exactly as the prompt found it.
+        if (phase?.kind === "awaiting-approval") {
+            if (this.phase?.kind !== "awaiting-approval") {
+                this.displaced = { phase: this.phase, startedAt: this.phaseStartedAt };
+            }
+        }
+        else {
+            this.displaced = null;
+        }
+        const before = phaseIdentity(this.phase);
+        this.phase = phase;
+        if (phaseIdentity(phase) !== before)
+            this.phaseStartedAt = Date.now();
+        if (phase === null) {
+            // A cleared phase means "nothing is happening" — hide rather than
+            // redraw a bare progress prefix between turns.
+            this.hideLine();
+            return;
+        }
+        this.refresh();
+    }
+    progress(state) {
+        if (this.closed)
+            return;
+        this.progressState = state;
+        this.refresh();
+    }
+    toolLifecycle(event) {
+        if (this.closed)
+            return;
+        if (event.event === "start") {
+            this.toolStart = { label: event.label, at: Date.now() };
+            this.setPhase({ kind: "calling-tool", label: event.label });
+            return;
+        }
+        const started = this.toolStart?.label === event.label ? this.toolStart : null;
+        this.toolStart = null;
+        if (this.phase?.kind === "calling-tool")
+            this.phase = null;
+        // Duration is measured (start→end timestamps), never animated — so it is
+        // honest even with CRUXY_NO_SPINNER; shown only once it means something.
+        const elapsed = started === null ? 0 : Date.now() - started.at;
+        const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
+        this.note(`${event.ok ? "✓" : "✗"} ${event.label}${suffix}`);
+    }
+    promptResolved() {
+        if (this.closed)
+            return;
+        if (this.phase?.kind !== "awaiting-approval")
+            return;
+        const displaced = this.displaced;
+        this.displaced = null;
+        this.phase = displaced?.phase ?? null;
+        // Restore the ORIGINAL clock: a long tool call approved late reports
+        // wall-time since it started, matching the committed end note.
+        this.phaseStartedAt = displaced?.startedAt ?? Date.now();
+        if (this.phase === null) {
+            this.hideLine();
+            return;
+        }
+        this.refresh();
+    }
+    endTurn() {
+        if (this.closed)
+            return;
+        // The turn's phase is over; step progress belongs to the plan executor
+        // and survives until it says otherwise.
+        this.phase = null;
+        this.rawStatus = null;
+        this.displaced = null;
+        this.hideLine();
+        this.commit(this.highlighter.flush());
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.endTurn();
+        this.closed = true;
+    }
+}

package/dist/render/types.d.ts

@@ -0,0 +1,160 @@
+import type { ActionPreview } from "../tools/types.js";
+/**
+ * The streaming render seam (U.2): the agent loop talks to a
+ * {@link StreamRenderer}, never to raw stdout. Two implementations exist —
+ * `TtyRenderer` (managed one-line live region, append-only committed content)
+ * and `PlainRenderer` (append-only, zero ANSI) — picked by the factory from
+ * detected {@link RenderCapabilities}. Same swappable discipline as
+ * `Formatter`/`VectorStore`.
+ */
+/**
+ * What the output medium supports, detected once at construction (see
+ * `detectCapabilities`). Renderers and the factory key off these flags; nothing
+ * downstream re-probes the environment.
+ */
+export interface RenderCapabilities {
+    /** The primary output stream is a terminal. */
+    tty: boolean;
+    /** Emit ANSI color (NO_COLOR / FORCE_COLOR / TTY resolved; `TERM=dumb` → false). */
+    color: boolean;
+    /** Cursor-control sequences are safe (`tty` and not `TERM=dumb`). */
+    cursor: boolean;
+    /** Animation is welcome (`cursor` and CRUXY_NO_SPINNER unset). */
+    spinner: boolean;
+    /** Terminal columns; 80 when unknown (non-TTY). */
+    width: number;
+}
+/** Accumulated token usage the loop already tracks (U.4) — never fabricated. */
+export interface TokenUsage {
+    input: number;
+    output: number;
+}
+/**
+ * Semantic live-state phases (U.4). The loop and the approval seam emit these
+ * instead of format strings; renderers decide presentation per capability.
+ * One phase is live at a time — it is a register, not a queue.
+ */
+export type RenderPhase = 
+/** Waiting on the model. `tokens` = usage accumulated so far, omitted at 0. */
+{
+    kind: "thinking";
+    tokens?: TokenUsage;
+}
+/** A tool call is executing; `label` is the human form ("read_file src/x.ts"). */
+ | {
+    kind: "calling-tool";
+    label: string;
+}
+/** An interactive prompt owns the terminal — the live line must yield to it. */
+ | {
+    kind: "awaiting-approval";
+}
+/** A plan step is active but the model is not yet engaged (C.31). */
+ | {
+    kind: "executing-step";
+}
+/** A subagent is running its task (C.14); `label` is the (truncated) task. */
+ | {
+    kind: "subagent";
+    label: string;
+};
+/**
+ * Plan-mode step progress (U.4/C.31): rendered as a persistent `[i/n] title`
+ * prefix on the live line. A separate register from {@link RenderPhase} with a
+ * separate owner (the plan executor), so `endTurn` clearing the loop's phase
+ * can never wipe step context mid-step.
+ */
+export interface ProgressState {
+    step: number;
+    of: number;
+    title: string;
+}
+/**
+ * Tool-call lifecycle (U.4): `start` paints live state and starts the honest
+ * elapsed clock; `end` commits the `✓/✗` trail note (with a duration suffix
+ * when the measured start→end gap crossed the threshold — never estimated).
+ */
+export type ToolLifecycleEvent = {
+    event: "start";
+    label: string;
+} | {
+    event: "end";
+    label: string;
+    ok: boolean;
+};
+/**
+ * How the agent loop paints a turn. The contract that keeps output flicker-free:
+ *
+ * - **Committed content is append-only.** `write`/`note`/`preview` output is
+ *   never repainted, moved, or cleared.
+ * - **Transient state is one line.** `status` owns a single live line that is
+ *   redrawn in place and erased before any committed write lands.
+ *
+ * Call shape per user turn: `beginTurn` → per model turn: `write`* +
+ * `endSegment`, with `status`/`note`/`preview` between segments → `endTurn`.
+ * All methods must be safe to call in any environment — degradation is the
+ * implementation's job, not the caller's.
+ */
+export interface StreamRenderer {
+    readonly caps: RenderCapabilities;
+    /** Start a user turn: reset leading-newline trim and code-fence state. */
+    beginTurn(): void;
+    /**
+     * Append streamed assistant text. Must forward promptly — implementations may
+     * hold back at most the current line (for fence detection), never the block
+     * or the response. Dismisses any live status first.
+     */
+    write(delta: string): void;
+    /**
+     * Close one model-turn text segment: flush any held partial line / open
+     * fence and terminate with a single newline (only if the segment produced
+     * visible text), so whatever follows starts on its own line.
+     */
+    endSegment(): void;
+    /** A committed one-line chrome note (e.g. `✓ read_file src/x.ts`), dim when colored. */
+    note(text: string): void;
+    /** A committed diff/action preview, rendered by the shared diff renderer. */
+    preview(preview: ActionPreview): void;
+    /**
+     * Replace the transient status line ("thinking…", "running bash…"); `null`
+     * clears it. Where in-place updates are impossible this may drop the text —
+     * status is progress decor, never information of record (use `note` for that).
+     * Ad-hoc/legacy; production callers use the typed U.4 methods below.
+     */
+    status(text: string | null): void;
+    /**
+     * Set (or clear) the semantic live phase (U.4). Rendered into the same
+     * managed status line; `awaiting-approval` yields the line to the prompt.
+     * PlainRenderer drops phases — transient state has no meaning append-only.
+     */
+    setPhase(phase: RenderPhase | null): void;
+    /**
+     * Set (or clear) plan-step progress (U.4). Persists across phase changes and
+     * `endTurn` — only the plan executor clears it. Rendered as an `[i/n] title`
+     * prefix on the live line; dropped by PlainRenderer.
+     */
+    progress(state: ProgressState | null): void;
+    /**
+     * Tool-call lifecycle (U.4): `start` → live "label…" state (+ elapsed clock),
+     * `end` → the committed `✓/✗ label` note, with an honest duration suffix for
+     * long calls. Replaces the loop's ad-hoc status/note pair.
+     */
+    toolLifecycle(event: ToolLifecycleEvent): void;
+    /**
+     * The interactive prompt released the terminal (its key/line read resolved):
+     * the pair-closer for `awaiting-approval`. Restores the phase the prompt
+     * displaced — with its original clock, so a long tool call approved late
+     * still reports honest wall-time. No-op where there is no live region.
+     */
+    promptResolved(): void;
+    /** End the user turn: clear any status and the live phase (never progress), flush everything held. */
+    endTurn(): void;
+    /** Release resources (spinner timer). Further calls are no-ops. */
+    close(): void;
+}
+/** The minimal stream surface a renderer writes to. Injectable for tests. */
+export interface RenderStream {
+    isTTY?: boolean;
+    columns?: number;
+    write(text: string): unknown;
+}

package/dist/render/types.js

@@ -0,0 +1 @@
+export {};

package/dist/subagent/budget.d.ts

@@ -0,0 +1,34 @@
+import type { Usage } from "@cruxy/sdk";
+import type { LoopBudget } from "../agent/loop.js";
+import type { BudgetLimits } from "./types.js";
+/**
+ * The subagent budget (C.14): iteration + token + optional wall-clock caps,
+ * checked by the agent loop before every model turn (see `LoopBudget`). A
+ * tripped cap stops the run with a human-readable reason — the subagent
+ * returns a partial result, it never runs unbounded.
+ */
+/**
+ * Resolve the effective limits for one spawn: start from the configured
+ * ceilings and let overrides only *narrow* them. A request above a ceiling is
+ * clamped down, not honored — "budget overrides within limits" by construction.
+ */
+export declare function resolveBudget(defaults: BudgetLimits, overrides?: Partial<BudgetLimits>): BudgetLimits;
+/**
+ * A live budget for one subagent run. The wall clock starts at construction
+ * (spawn time); the clock source is injectable so tests never sleep.
+ */
+export declare class Budget implements LoopBudget {
+    private readonly limits;
+    private readonly now;
+    private readonly startedAt;
+    constructor(limits: BudgetLimits, now?: () => number);
+    /**
+     * The reason to stop before the next model turn, or `null` to continue.
+     * Checked at iteration boundaries — the in-flight turn always completes, so
+     * overshoot is bounded by one turn.
+     */
+    exceeded(state: {
+        iterations: number;
+        usage: Usage;
+    }): string | null;
+}

package/dist/subagent/budget.js

@@ -0,0 +1,57 @@
+/**
+ * The subagent budget (C.14): iteration + token + optional wall-clock caps,
+ * checked by the agent loop before every model turn (see `LoopBudget`). A
+ * tripped cap stops the run with a human-readable reason — the subagent
+ * returns a partial result, it never runs unbounded.
+ */
+/**
+ * Resolve the effective limits for one spawn: start from the configured
+ * ceilings and let overrides only *narrow* them. A request above a ceiling is
+ * clamped down, not honored — "budget overrides within limits" by construction.
+ */
+export function resolveBudget(defaults, overrides) {
+    const clamp = (ceiling, requested) => requested !== undefined && requested > 0
+        ? Math.min(ceiling, requested)
+        : ceiling;
+    const timeoutMs = defaults.timeoutMs !== undefined
+        ? clamp(defaults.timeoutMs, overrides?.timeoutMs)
+        : overrides?.timeoutMs;
+    return {
+        maxIterations: clamp(defaults.maxIterations, overrides?.maxIterations),
+        maxTokens: clamp(defaults.maxTokens, overrides?.maxTokens),
+        ...(timeoutMs !== undefined && timeoutMs > 0 ? { timeoutMs } : {}),
+    };
+}
+/**
+ * A live budget for one subagent run. The wall clock starts at construction
+ * (spawn time); the clock source is injectable so tests never sleep.
+ */
+export class Budget {
+    limits;
+    now;
+    startedAt;
+    constructor(limits, now = Date.now) {
+        this.limits = limits;
+        this.now = now;
+        this.startedAt = now();
+    }
+    /**
+     * The reason to stop before the next model turn, or `null` to continue.
+     * Checked at iteration boundaries — the in-flight turn always completes, so
+     * overshoot is bounded by one turn.
+     */
+    exceeded(state) {
+        const { maxIterations, maxTokens, timeoutMs } = this.limits;
+        if (state.iterations >= maxIterations) {
+            return `iteration cap reached (${maxIterations})`;
+        }
+        const tokens = state.usage.input_tokens + state.usage.output_tokens;
+        if (tokens >= maxTokens) {
+            return `token cap reached (${tokens} of ${maxTokens})`;
+        }
+        if (timeoutMs !== undefined && this.now() - this.startedAt >= timeoutMs) {
+            return `time cap reached (${timeoutMs}ms)`;
+        }
+        return null;
+    }
+}

package/dist/subagent/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./budget.js";
+export * from "./registry-scope.js";
+export * from "./orchestrator.js";
+export * from "./spawn-tool.js";

package/dist/subagent/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./budget.js";
+export * from "./registry-scope.js";
+export * from "./orchestrator.js";
+export * from "./spawn-tool.js";

package/dist/subagent/orchestrator.d.ts

@@ -0,0 +1,67 @@
+import type { Provider } from "@cruxy/sdk";
+import type { ApprovalDecision } from "../approval/types.js";
+import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
+import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
+import type { SubagentResult, SubagentSpec } from "./types.js";
+/**
+ * Everything a spawn needs from the surrounding session, injected by the
+ * session factory so this package stays free of wiring detail. Shared members
+ * are stateless (provider, config, logger) or deliberately run-scoped (the
+ * renderer, and — via `makeChildApproval` — the checkpoint gate); everything
+ * stateful (history, registry, allowlist, budget) is built fresh per spawn.
+ */
+export interface SubagentOrchestratorDeps {
+    provider: Provider;
+    config: CruxyConfig;
+    /** The parent's registry — the ceiling every child scope derives from. */
+    parentRegistry: ToolRegistry;
+    cwd: string;
+    logger: ToolContext["logger"];
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    projectInstructions?: string | null;
+    renderer?: StreamRenderer;
+    /**
+     * Build a fresh, fully-wrapped approval gate for one child run: a NEW
+     * `ApprovalService` (so the child gets its own empty session allowlist —
+     * parent grants never silently widen child authority) behind the same
+     * checkpoint hook as the parent (so child mutations land under the run's
+     * one checkpoint, C.32).
+     */
+    makeChildApproval(): (action: ApproveAction) => Promise<ApprovalDecision>;
+}
+/**
+ * Spawns subagents (C.14): the existing agent loop re-driven over isolated
+ * state. Each spawn builds a fresh history seeded with only the task, a
+ * scoped-down registry, a fresh approval gate, and a hard budget, runs
+ * `runAgent` to completion (or cap), and folds the outcome into a compact
+ * {@link SubagentResult}. The child transcript is dropped here — the parent
+ * never sees it.
+ *
+ * Spawns are sequential by construction: the loop awaits each tool call, so
+ * two spawn requests in one turn run one after the other in deterministic
+ * order. Parallel fan-out is C.33's job — `spawn` is a self-contained async
+ * unit with no cross-spawn state, so it slots in without reshaping this class.
+ */
+export declare class SubagentOrchestrator {
+    private readonly deps;
+    constructor(deps: SubagentOrchestratorDeps);
+    /**
+     * Run one subagent to completion. `parentDepth` is the spawner's depth (the
+     * main agent is 0); spawning past `subagent.maxDepth` throws
+     * `CRUXY_E_SUBAGENT_DEPTH_EXCEEDED` — the spawn tool is also structurally
+     * withheld at the cap, so this throw is the fail-loud backstop.
+     *
+     * Never rejects on a *child* failure — provider or tool crashes come back as
+     * `status: "failed"` for the parent to reason over. The two exceptions that
+     * do propagate: the depth cap (above) and `CRUXY_E_APPROVAL_REQUIRED`
+     * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
+     * not a way to swallow it).
+     */
+    spawn(spec: SubagentSpec, parentDepth: number): Promise<SubagentResult>;
+    /** Map the child's AgentResult to the structured, transcript-free shape. */
+    private toResult;
+}