@cruxy/cli 0.8.0 → 0.10.0

package/dist/render/plain-renderer.js

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
+import { ELAPSED_AFTER_MS, formatElapsed } from "./state.js";
 /**
  * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
  * cursor-control sequences ever, and no color unless the capabilities say so
@@ -20,6 +21,8 @@ export class PlainRenderer {
     /** Per-turn leading-newline trim; also tells endSegment whether to newline. */
     print;
     wroteInSegment = false;
+    /** In-flight tool call (serial by contract) for the end-note duration. */
+    toolStart = null;
     constructor(caps, out, err) {
         this.caps = caps;
         this.out = out;
@@ -56,6 +59,29 @@ export class PlainRenderer {
     status() {
         // Append-only medium: transient state is dropped by design.
     }
+    setPhase() {
+        // Phases are live-region state; there is no live region here (U.4).
+    }
+    progress() {
+        // The committed plan trail (C.31, via PromptIO) is the record in this
+        // medium; a live [i/n] prefix would just duplicate it line by line.
+    }
+    toolLifecycle(event) {
+        if (event.event === "start") {
+            // Silent: the end note is the single durable line per call — a start
+            // line too would double the chrome in CI logs for no information.
+            this.toolStart = { label: event.label, at: Date.now() };
+            return;
+        }
+        const started = this.toolStart?.label === event.label ? this.toolStart : null;
+        this.toolStart = null;
+        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() {
+        // No live region to restore.
+    }
     endTurn() { }
     close() { }
 }

package/dist/render/state.d.ts

@@ -0,0 +1,31 @@
+import type { ProgressState, RenderPhase } from "./types.js";
+/**
+ * The U.4 state→text mapping: pure data → string, like plan/render.ts and
+ * diff.ts, so both renderers (and tests) share one composition with no
+ * terminal in sight. Color is deliberately absent — the live line is drawn
+ * dim as a whole by the TTY renderer; state text is content, not chrome.
+ */
+/**
+ * Threshold before elapsed time appears on a live state or a committed tool
+ * note. Below this, a timer is noise; above it, it's the answer to "is this
+ * stuck?".
+ */
+export declare const ELAPSED_AFTER_MS = 5000;
+/** `342`, `1.2k`, `3.4M` — token counts at status-line width. */
+export declare function formatTokens(n: number): string;
+/** `37s`, `2m08s` — durations at status-line width. */
+export declare function formatElapsed(ms: number): string;
+/** The live-line text for a phase. `awaiting-approval` never renders (the line hides). */
+export declare function describePhase(phase: RenderPhase): string;
+/**
+ * Identity key for the elapsed clock: the clock resets when the phase becomes
+ * a *different activity*, not on every payload update — a thinking phase that
+ * gains token counts keeps its start time; a new tool label starts fresh.
+ */
+export declare function phaseIdentity(phase: RenderPhase | null): string;
+/**
+ * Compose the single live line: `[2/5] title · read_file src/x.ts… (12s)`.
+ * Elapsed appears only past {@link ELAPSED_AFTER_MS} — callers pass it only
+ * when they can keep it ticking honestly (no timer → no frozen number).
+ */
+export declare function composeStatusLine(progress: ProgressState | null, phase: RenderPhase | null, elapsedMs?: number): string;

package/dist/render/state.js

@@ -0,0 +1,83 @@
+/**
+ * The U.4 state→text mapping: pure data → string, like plan/render.ts and
+ * diff.ts, so both renderers (and tests) share one composition with no
+ * terminal in sight. Color is deliberately absent — the live line is drawn
+ * dim as a whole by the TTY renderer; state text is content, not chrome.
+ */
+/**
+ * Threshold before elapsed time appears on a live state or a committed tool
+ * note. Below this, a timer is noise; above it, it's the answer to "is this
+ * stuck?".
+ */
+export const ELAPSED_AFTER_MS = 5_000;
+/** `342`, `1.2k`, `3.4M` — token counts at status-line width. */
+export function formatTokens(n) {
+    if (n < 1_000)
+        return String(n);
+    const scaled = n < 1_000_000 ? n / 1_000 : n / 1_000_000;
+    const unit = n < 1_000_000 ? "k" : "M";
+    const s = scaled.toFixed(1);
+    return (s.endsWith(".0") ? s.slice(0, -2) : s) + unit;
+}
+/** `37s`, `2m08s` — durations at status-line width. */
+export function formatElapsed(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+/** The live-line text for a phase. `awaiting-approval` never renders (the line hides). */
+export function describePhase(phase) {
+    switch (phase.kind) {
+        case "thinking": {
+            const t = phase.tokens;
+            // Honest numbers only: no usage yet → no figure at all.
+            return t && t.input + t.output > 0
+                ? `thinking… · tokens ↑${formatTokens(t.input)} ↓${formatTokens(t.output)}`
+                : "thinking…";
+        }
+        case "calling-tool":
+            return `${phase.label}…`;
+        case "awaiting-approval":
+            return "awaiting approval…";
+        case "executing-step":
+            return "working…";
+        case "subagent":
+            return `subagent: ${phase.label}…`;
+    }
+}
+/**
+ * Identity key for the elapsed clock: the clock resets when the phase becomes
+ * a *different activity*, not on every payload update — a thinking phase that
+ * gains token counts keeps its start time; a new tool label starts fresh.
+ */
+export function phaseIdentity(phase) {
+    if (phase === null)
+        return "";
+    switch (phase.kind) {
+        case "calling-tool":
+            return `calling-tool:${phase.label}`;
+        case "subagent":
+            return `subagent:${phase.label}`;
+        default:
+            return phase.kind;
+    }
+}
+/**
+ * Compose the single live line: `[2/5] title · read_file src/x.ts… (12s)`.
+ * Elapsed appears only past {@link ELAPSED_AFTER_MS} — callers pass it only
+ * when they can keep it ticking honestly (no timer → no frozen number).
+ */
+export function composeStatusLine(progress, phase, elapsedMs) {
+    const parts = [];
+    if (progress)
+        parts.push(`[${progress.step}/${progress.of}] ${progress.title}`);
+    if (phase)
+        parts.push(describePhase(phase));
+    const line = parts.join(" · ");
+    if (elapsedMs !== undefined && elapsedMs >= ELAPSED_AFTER_MS) {
+        return `${line} (${formatElapsed(elapsedMs)})`;
+    }
+    return line;
+}

package/dist/render/tty-renderer.d.ts

@@ -1,5 +1,5 @@
 import type { ActionPreview } from "../tools/types.js";
-import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.js";
+import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
 /**
  * The interactive renderer: committed content is append-only; the one transient
  * thing on screen is a single managed status line, redrawn in place.
@@ -16,6 +16,14 @@ import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.j
  *
  * 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 declare class TtyRenderer implements StreamRenderer {
     readonly caps: RenderCapabilities;
@@ -24,7 +32,18 @@ export declare class TtyRenderer implements StreamRenderer {
     private print;
     private highlighter;
     private wroteInSegment;
-    private statusText;
+    /** Ad-hoc/legacy status text; wins over composed state when set. */
+    private rawStatus;
+    private phase;
+    private progressState;
+    /** When the current phase *identity* began — drives honest elapsed display. */
+    private phaseStartedAt;
+    /** In-flight tool call (serial by contract) for end-note duration. */
+    private toolStart;
+    /** Phase (+ its clock) displaced by an approval prompt, for promptResolved. */
+    private displaced;
+    /** Whether the live line is currently drawn on screen. */
+    private lineVisible;
     private timer;
     private frame;
     private closed;
@@ -32,16 +51,33 @@ export declare class TtyRenderer implements StreamRenderer {
     private newPrinter;
     /** Append committed content, erasing the status line first if one is live. */
     private commit;
-    /** Erase the live status line (if any) and stop the spinner. */
-    private dismissStatus;
+    /**
+     * 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.)
+     */
+    private hideLine;
     private stopTimer;
-    private drawStatus;
+    /**
+     * 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).
+     */
+    private currentLine;
+    /** Redraw the live line from current state, or hide it when there is none. */
+    private refresh;
+    private drawLine;
     beginTurn(): void;
     write(delta: string): void;
     endSegment(): void;
     note(text: string): void;
     preview(preview: ActionPreview): void;
     status(text: string | null): void;
+    setPhase(phase: RenderPhase | null): void;
+    progress(state: ProgressState | null): void;
+    toolLifecycle(event: ToolLifecycleEvent): void;
+    promptResolved(): void;
     endTurn(): void;
     close(): void;
 }

package/dist/render/tty-renderer.js

@@ -2,6 +2,7 @@ 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. */
@@ -24,6 +25,14 @@ const SPINNER_INTERVAL_MS = 100;
  *
  * 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;
@@ -32,7 +41,18 @@ export class TtyRenderer {
     print;
     highlighter;
     wroteInSegment = false;
-    statusText = null;
+    /** 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;
@@ -52,15 +72,23 @@ export class TtyRenderer {
     commit(text) {
         if (text === "")
             return;
-        this.dismissStatus();
+        // 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 live status line (if any) and stop the spinner. */
-    dismissStatus() {
-        if (this.statusText === null)
+    /**
+     * 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.statusText = null;
+        this.lineVisible = false;
         this.stopTimer();
         this.out.write(CLEAR_LINE);
     }
@@ -70,18 +98,53 @@ export class TtyRenderer {
             this.timer = null;
         }
     }
-    drawStatus() {
-        if (this.statusText === 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 text = this.statusText.length > room
-            ? this.statusText.slice(0, Math.max(0, room - 1)) + "…"
-            : this.statusText;
-        this.out.write(`${CLEAR_LINE}${this.colors.cyan(glyph)} ${this.colors.dim(text)}`);
+        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);
@@ -119,25 +182,89 @@ export class TtyRenderer {
     status(text) {
         if (this.closed)
             return;
+        this.rawStatus = text;
         if (text === null) {
-            this.dismissStatus();
+            // Legacy clear semantics: hide now, redraw only on the next transition.
+            this.hideLine();
             return;
         }
-        this.statusText = text;
-        this.drawStatus();
-        if (this.caps.spinner && this.timer === null) {
-            this.timer = setInterval(() => {
-                this.frame++;
-                this.drawStatus();
-            }, SPINNER_INTERVAL_MS);
-            // Never hold the process open for a spinner.
-            this.timer.unref?.();
+        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;
-        this.dismissStatus();
+        // 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() {

package/dist/render/types.d.ts

@@ -24,6 +24,64 @@ export interface RenderCapabilities {
     /** 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:
  *
@@ -61,9 +119,35 @@ export interface StreamRenderer {
      * 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;
-    /** End the user turn: clear any status, flush everything held. */
+    /**
+     * 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;

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";