@cruxy/cli 1.2.0 → 1.3.0

package/dist/agent/context.js

@@ -0,0 +1,178 @@
+import { COMPACTION_MARKER } from "./prompts.js";
+/** Characters a single content block contributes to the estimate. */
+function blockChars(block) {
+    switch (block.type) {
+        case "text":
+            return block.text.length;
+        case "tool_use":
+            return block.name.length + JSON.stringify(block.input).length;
+        case "tool_result":
+            return block.content.length;
+    }
+}
+/** Characters one message contributes. Block structure and role labels are ignored. */
+export function messageChars(message) {
+    if (typeof message.content === "string")
+        return message.content.length;
+    let chars = 0;
+    for (const block of message.content)
+        chars += blockChars(block);
+    return chars;
+}
+/** Chars → tokens, the one place the chars/4 heuristic is applied. */
+export function charsToTokens(chars) {
+    return Math.ceil(chars / 4);
+}
+/**
+ * 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 message of messages)
+        chars += messageChars(message);
+    return charsToTokens(chars);
+}
+/** Compute a reading from a history — pure, and shared by the gauge and `/context`. */
+export function readContext(messages, budget) {
+    // Deliberately the SAME expression `compactIfOverThreshold` branches on: the
+    // reserve covers the system prompt and tool schemas that `estimateTokens`
+    // never sees, and omitting it here would under-report by ~4.5k tokens and let
+    // the panel read "comfortable" while the seam was about to compact.
+    const used = estimateTokens(messages) + budget.reserveTokens;
+    const total = budget.maxTokens;
+    return {
+        used,
+        total,
+        fraction: total <= 0 ? 1 : Math.min(1, Math.max(0, used / total)),
+        compactAt: Math.round(budget.compactThreshold * total),
+    };
+}
+/**
+ * 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. The
+ * synthetic compaction-summary user message is also string content, so a repeat
+ * compaction always finds at least the previous summary as a clean cut.
+ *
+ * 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).
+ *
+ * Extracted from `Session` (P6 track 3) so `/context` can report what compaction
+ * would do by calling the function that decides what it does. A second
+ * implementation for the explanation would be free to be subtly wrong exactly
+ * where it mattered.
+ */
+export function findCut(messages, keepRecentMessages) {
+    const start = messages.length - keepRecentMessages;
+    for (let i = start; i >= 1; i--) {
+        const message = messages[i];
+        if (message.role === "user" && typeof message.content === "string")
+            return i;
+    }
+    return null;
+}
+/** Which part a message belongs to. */
+function classify(message) {
+    if (typeof message.content === "string") {
+        // The synthetic pair a previous compaction spliced in. Worth its own bucket:
+        // "40% of your context is a summary of earlier context" is a different fact
+        // from "40% is your prompts", and it is the one that says compaction has
+        // already run.
+        return message.content.startsWith(COMPACTION_MARKER)
+            ? "summaries"
+            : "prompts";
+    }
+    if (message.role === "user")
+        return "tool results";
+    return message.content.some((b) => b.type === "tool_use")
+        ? "tool calls"
+        : "assistant";
+}
+/** A one-line excerpt of a message, for recognition rather than reading. */
+function excerpt(message, max = 60) {
+    let text;
+    if (typeof message.content === "string") {
+        text = message.content;
+    }
+    else {
+        const first = message.content[0];
+        text =
+            first === undefined
+                ? ""
+                : first.type === "text"
+                    ? first.text
+                    : first.type === "tool_use"
+                        ? first.name
+                        : first.content;
+    }
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Analyse a history against a budget. Pure; no I/O, no theme, no rendering.
+ *
+ * @param topN how many individual messages to name as the largest contributors.
+ */
+export function contextReport(messages, budget, topN = 5) {
+    const charsByPart = new Map();
+    const contributors = [];
+    for (const [index, message] of messages.entries()) {
+        const chars = messageChars(message);
+        const part = classify(message);
+        const bucket = charsByPart.get(part) ?? { chars: 0, messages: 0 };
+        bucket.chars += chars;
+        bucket.messages += 1;
+        charsByPart.set(part, bucket);
+        contributors.push({ chars, message, index });
+    }
+    const parts = [...charsByPart.entries()]
+        .map(([part, b]) => ({
+        part,
+        tokens: charsToTokens(b.chars),
+        messages: b.messages,
+    }))
+        .filter((p) => p.tokens > 0)
+        .sort((a, b) => b.tokens - a.tokens);
+    const largest = contributors
+        .filter((c) => c.chars > 0)
+        .sort((a, b) => b.chars - a.chars)
+        .slice(0, topN)
+        .map((c) => ({
+        label: classify(c.message),
+        excerpt: excerpt(c.message),
+        tokens: charsToTokens(c.chars),
+        position: c.index + 1,
+    }));
+    const cut = findCut(messages, budget.keepRecentMessages);
+    const reading = readContext(messages, budget);
+    return {
+        reading,
+        messages: messages.length,
+        reserveTokens: budget.reserveTokens,
+        parts,
+        largest,
+        compaction: {
+            cut,
+            droppedMessages: cut ?? 0,
+            droppedTokens: cut === null ? 0 : estimateTokens(messages.slice(0, cut)),
+            keptMessages: cut === null ? messages.length : messages.length - cut,
+            keptTokens: cut === null
+                ? estimateTokens(messages)
+                : estimateTokens(messages.slice(cut)),
+            // Compared against the UNROUNDED product, exactly as
+            // `compactIfOverThreshold` does — `compactAt` is rounded for display, and
+            // a report claiming to say what compaction would do must not disagree
+            // with the seam over a fraction of a token.
+            overThreshold: reading.used > budget.compactThreshold * budget.maxTokens,
+        },
+    };
+}

package/dist/agent/index.js

@@ -1,3 +1,4 @@
 export * from "./loop.js";
+export * from "./mode.js";
 export * from "./session.js";
 export * from "./prompts.js";

package/dist/agent/loop.js

@@ -24,6 +24,11 @@ export async function runAgent(args) {
     // gateway does not offer throws CRUXY_E_ROUTING_TIER_UNAVAILABLE here — so a
     // misrouted run never reaches provider.stream (no request sent with the wrong
     // tier), and never silently falls back to a different one.
+    //
+    // Resolving per RUN, not per iteration, is still right after P6 track 1 made
+    // the choice mutable: a `/model` mid-turn is impossible (the input loop has
+    // released stdin and is awaiting `session.send`), and a run that changed model
+    // between its own iterations would attribute one history to two tiers.
     const routed = args.router
         ? resolveTaskModel(args.router, args.taskClass ?? "main-turn")
         : null;
@@ -38,7 +43,11 @@ export async function runAgent(args) {
     }
 }
 /** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
-async function driveLoop(args, renderer, routed) {
+async function driveLoop(args, renderer, 
+// `tier` is optional because a router may decline and send the request as
+// `auto` — no tier was chosen client-side, so there is none to report until
+// the gateway's routing frame arrives. See `resolveTaskModel`.
+routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
@@ -116,6 +125,12 @@ async function driveLoop(args, renderer, routed) {
         // true and is recorded as a real 0.
         let sawUsage = false;
         const reqUsage = { input_tokens: 0, output_tokens: 0 };
+        // The served tier arrives on the stream's OPENING frame, but usage is only
+        // reported once the stream has closed — so it is held here across the whole
+        // request, exactly like `sawUsage`. Absent for backends that report no
+        // routing, which is why the fallback below still exists.
+        let servedTier;
+        let routingMode;
         // Live progress while waiting on the model; dismissed by the first delta.
         // Token context is whatever the loop has actually accumulated (U.4): zero
         // on the first turn → no figure shown, never a fabricated number.
@@ -133,6 +148,20 @@ async function driveLoop(args, renderer, routed) {
             ...(routed ? { model: routed.model } : {}),
         })) {
             switch (ev.type) {
+                case "routing":
+                    servedTier = ev.routing.tier;
+                    routingMode = ev.routing.mode;
+                    // Publish to the renderer HERE, not at the `setPhase` above. That one
+                    // fires before `provider.stream` is called, so the served tier is not
+                    // knowable yet and it can only carry `routed?.tier` — what this run
+                    // ASKED for. This frame is the first moment the backend's answer
+                    // exists, and it is the answer worth showing: it resolves `auto`, and
+                    // it reflects a downgrade the client never chose.
+                    renderer?.servedRouting({
+                        tier: ev.routing.tier,
+                        ...(ev.routing.mode !== undefined ? { mode: ev.routing.mode } : {}),
+                    });
+                    break;
                 case "text_delta":
                     turnText += ev.text;
                     renderer?.write(ev.text);
@@ -178,8 +207,18 @@ async function driveLoop(args, renderer, routed) {
         // event arrived, or `undefined` (unknown) when the provider reported none. A
         // stream that threw above never reaches here, so failed requests aren't
         // recorded with a misleading zero.
+        // THE BACKEND WINS on tier. `routed?.tier` is what this run ASKED for;
+        // `servedTier` is what the gateway says actually ran, which is not the same
+        // claim — a "auto" request is resolved server-side, and any request can be
+        // downgraded under budget pressure. Attributing tokens to the tier we asked
+        // for would misreport exactly the case worth knowing about. The client
+        // choice remains the fallback for backends that report no routing at all.
+        // `routingMode` travels alongside so a difference between the two is
+        // explainable after the fact ("auto_degraded") rather than an unexplained
+        // tier nobody selected.
         args.onRequestUsage?.({
-            tier: routed?.tier,
+            tier: servedTier ?? routed?.tier,
+            ...(routingMode !== undefined ? { routingMode } : {}),
             usage: sawUsage ? { ...reqUsage } : undefined,
         });
         // ── Record the assistant turn ───────────────────────────────────────────

package/dist/agent/mode.js

@@ -0,0 +1,103 @@
+/**
+ * Session modes (P5 track 3) — the one piece of state that says how much a turn
+ * does without asking.
+ *
+ * Two facts govern that, and before P5 they were kept in different places and at
+ * different lifetimes: plan mode lived on the `Session` (runtime, journaled,
+ * restored on resume) while auto-approve was a config key read from disk. The
+ * config key was also dead — nothing consumed `agent.autoApprove`, and
+ * `ApprovalConfigSchema` in the same file stated flatly that no auto-approve
+ * mode exists "not behind a footgun flag". One file promised something another
+ * refused to do.
+ *
+ * A mode is the cross product of the two, named. That is what makes it a
+ * SUBSUMPTION rather than a third source of truth: `Session` holds exactly one
+ * mode and derives both booleans from it, so there is no state in which plan
+ * mode and the mode indicator can disagree.
+ *
+ * Auto-approve is deliberately a RUNTIME mode and only that — never a config
+ * key. A flag on disk silently disarms every approval in every session that
+ * loads it, with nothing on screen to say so; a mode is chosen in the session it
+ * affects, shown while it is active, and gone when the session ends.
+ */
+/**
+ * Cycle order, and the order every list of modes uses. Shift+Tab walks this
+ * ring; the last entry wraps to the first.
+ */
+export const SESSION_MODES = [
+    "manual",
+    "auto-approve",
+    "plan",
+    "full-auto",
+];
+/** The default for a session that says nothing — the pre-P5 behaviour exactly. */
+export const DEFAULT_MODE = "manual";
+/** The next mode in the ring. Total: every mode has a successor. */
+export function nextMode(mode) {
+    const i = SESSION_MODES.indexOf(mode);
+    return SESSION_MODES[(i + 1) % SESSION_MODES.length];
+}
+/** Whether this mode proposes a plan before executing (C.31). */
+export function modePlans(mode) {
+    return mode === "plan" || mode === "full-auto";
+}
+/** Whether this mode allows gated actions without prompting. */
+export function modeAutoApproves(mode) {
+    return mode === "auto-approve" || mode === "full-auto";
+}
+/** Short label for the status line and the mode indicator. */
+export const MODE_LABELS = {
+    manual: "manual",
+    "auto-approve": "auto-approve",
+    plan: "plan",
+    "full-auto": "full-auto",
+};
+/**
+ * One line saying what the mode will actually do, shown when it changes.
+ *
+ * A mode that skips approvals has to SAY it skips approvals at the moment it is
+ * switched on. The whole objection to the config flag was that it disarmed the
+ * gate with nothing on screen; a runtime mode that announced itself as vaguely
+ * as "auto-approve on" would reproduce the same problem more slowly.
+ *
+ * These lines must not overstate the mode either. Saying "including destructive
+ * ones" when the ceiling stops exactly those would teach the user to expect a
+ * silence that never comes — and, worse, teach them the gate is gone when it is
+ * not. Each auto line names the suppression AND its limit.
+ */
+export function modeDescription(mode) {
+    switch (mode) {
+        case "manual":
+            return "every action asks first";
+        case "auto-approve":
+            return "reversible actions run WITHOUT asking — irreversible ones still ask";
+        case "plan":
+            return "propose a plan for approval, then ask before each action";
+        case "full-auto":
+            return "propose a plan, then run it WITHOUT asking — irreversible actions still ask";
+    }
+}
+/**
+ * Parse a mode from user input (`/mode <name>`), or null when it names nothing.
+ * Never guesses: a typo must not silently arm auto-approve.
+ */
+export function parseMode(text) {
+    const want = text.trim().toLowerCase();
+    return SESSION_MODES.find((m) => m === want) ?? null;
+}
+/**
+ * Recover a mode from the two booleans an older session journaled.
+ *
+ * Sessions recorded before P5 carry `plan-mode` events and nothing else, so
+ * auto-approve reads false — which is right: it was not a thing that could be
+ * on. This is what lets a pre-P5 session resume into the mode it actually had.
+ */
+export function modeFromFlags(plans, autoApproves) {
+    if (plans && autoApproves)
+        return "full-auto";
+    if (plans)
+        return "plan";
+    if (autoApproves)
+        return "auto-approve";
+    return "manual";
+}

package/dist/agent/prompts.js

@@ -1,5 +1,5 @@
 /**
- * cruxy-code agent prompts.
+ * cruxy 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