@cspeach/cli 0.6.5 → 0.7.0

package/dist/agent/summarise-via-provider.js

@@ -0,0 +1,51 @@
+/**
+ * One-shot non-streaming text summarisation via an LLMProvider.
+ *
+ * The agent loop's createStream is designed for full agentic turns with
+ * tools, thinking, and multi-round interaction. /compact only needs the
+ * simplest case: send a system + user prompt to a small model, collect the
+ * text response, return it.
+ *
+ * This helper wraps provider.createStream into that simple shape so the
+ * compact command (and any future cheap-model utility) doesn't need to
+ * recreate the streaming event-loop boilerplate.
+ *
+ * NOT for tool-using calls. NOT for thinking-enabled calls. Pure text-in /
+ * text-out.
+ */
+/**
+ * Run a single non-streaming summarisation call.
+ *
+ * `system` is the instruction (what kind of summary you want).
+ * `user` is the content to summarise.
+ *
+ * Returns the accumulated text from the model's response. Throws on
+ * provider error or empty output.
+ */
+export async function summariseViaProvider(provider, system, user, opts) {
+    const stream = await provider.createStream({
+        model: opts.model,
+        max_tokens: opts.maxTokens ?? 4000,
+        system,
+        messages: [{ role: 'user', content: user }],
+    }, {
+        headers: opts.headers,
+        signal: opts.signal,
+    });
+    let accumulated = '';
+    for await (const event of stream) {
+        const type = event?.type;
+        if (type === 'content_block_delta') {
+            const delta = event.delta;
+            if (delta?.type === 'text_delta' && typeof delta.text === 'string') {
+                accumulated += delta.text;
+            }
+        }
+        // Ignore everything else — message_start/stop, usage events, etc.
+        // For one-shot text summarisation only content_block_delta matters.
+    }
+    if (!accumulated || accumulated.trim().length === 0) {
+        throw new Error('Summariser returned empty output.');
+    }
+    return accumulated;
+}

package/dist/approvals/jwt.js

@@ -12,22 +12,43 @@ export async function mintApprovalId(payload) {
         .sign(sessionKey);
 }
 export async function verifyAndSpendApprovalId(jwt, expectedObject, expectedOp) {
+    // 2026-05-15 (bug 7): the previous catch lumped EVERY thrown failure
+    // into `'invalid_signature'`, including expirations (which used to be
+    // sniffed via a fragile substring match on err.message). During the
+    // live session this surfaced `op_mismatch` errors as `invalid_signature`
+    // — extremely disorienting for whoever was debugging since it implied
+    // cryptographic corruption when the JWT was actually fine.
+    //
+    // The expiry path now uses jose's documented error code
+    // (`ERR_JWT_EXPIRED`); the signature path is reserved for the actual
+    // signature-verification failure code. Mismatch reasons (nonce, object,
+    // op) fall out of the post-verify checks below and are returned
+    // verbatim — no catch involved.
+    let payload;
     try {
-        const { payload } = await jwtVerify(jwt, sessionKey);
-        const p = payload;
-        if (usedNonces.has(p.nonce))
-            return { ok: false, reason: 'nonce_spent' };
-        if (p.object !== expectedObject)
-            return { ok: false, reason: 'object_mismatch' };
-        if (p.op !== expectedOp)
-            return { ok: false, reason: 'op_mismatch' };
-        usedNonces.add(p.nonce);
-        return { ok: true, payload: p };
+        const verified = await jwtVerify(jwt, sessionKey);
+        payload = verified.payload;
     }
     catch (err) {
-        if (String(err?.code).includes('JWTExpired') || String(err?.message).toLowerCase().includes('expired')) {
+        const code = typeof err?.code === 'string'
+            ? err.code
+            : '';
+        if (code === 'ERR_JWT_EXPIRED')
             return { ok: false, reason: 'expired' };
-        }
+        // Everything else from jose at this point is a structural / signature
+        // problem with the token itself (ERR_JWS_SIGNATURE_VERIFICATION_FAILED,
+        // ERR_JWS_INVALID, ERR_JWT_INVALID, …). All five surface to the user
+        // as the same actionable: "this token is not trustworthy — get a new
+        // one". Mapping them all to invalid_signature keeps the user-facing
+        // taxonomy short. Mismatch / spent-nonce paths NEVER reach this catch.
         return { ok: false, reason: 'invalid_signature' };
     }
+    if (usedNonces.has(payload.nonce))
+        return { ok: false, reason: 'nonce_spent' };
+    if (payload.object !== expectedObject)
+        return { ok: false, reason: 'object_mismatch' };
+    if (payload.op !== expectedOp)
+        return { ok: false, reason: 'op_mismatch' };
+    usedNonces.add(payload.nonce);
+    return { ok: true, payload };
 }

package/dist/commands/auto-compact.js

@@ -0,0 +1,94 @@
+/**
+ * Auto-compact orchestration — Phase 2 #9 (2026-05-16).
+ *
+ * Calls `runCompact` end-of-turn when the session has crossed
+ * `compact.auto_threshold_tokens` non-cached input tokens AND enough turns
+ * have passed since the last auto-compact run.
+ *
+ * Why end-of-turn (not start-of-turn): firing at the end means the cost
+ * (one Haiku call to summarise) is amortised over the user's natural
+ * "think before typing" pause. Firing at the start would delay the user's
+ * next response by ~3s. Same eventual savings; better felt latency.
+ *
+ * Why a separate file: the gating logic (threshold + throttle + opt-out)
+ * has enough branches to deserve isolated unit tests, and dispatch from
+ * `loop.ts` should stay one short call site.
+ *
+ * Safety: if the summariser throws, we LOG and CONTINUE — auto-compact
+ * failure must not take down the turn that just completed successfully.
+ * Worst case: the user sees a yellow note that auto-compact bailed, and
+ * the next /compact-eligible threshold check fires again.
+ */
+import chalk from 'chalk';
+import { saveSession } from '../session/store.js';
+import { runCompact, formatCompactResult, } from './compact.js';
+/**
+ * Pure decision function — no IO. Decides whether auto-compact should
+ * fire given the current session state and config. Extracted so the
+ * branching logic can be unit-tested without standing up a fake
+ * Summariser.
+ */
+export function shouldAutoCompact(input) {
+    const { sessionInputTokens, turnNumber, lastAutoCompactTurn, config } = input;
+    if (!config.auto_enabled) {
+        return { fire: false, reason: 'disabled' };
+    }
+    if (sessionInputTokens < config.auto_threshold_tokens) {
+        return { fire: false, reason: 'below-threshold' };
+    }
+    // Throttle: don't bounce. If we just ran auto-compact a few turns ago
+    // and the counter happens to be over again (it should fall sharply
+    // after a successful compact, but tool-heavy turns can still grow
+    // it), wait `min_turns_between_auto` before firing again.
+    const turnsSince = lastAutoCompactTurn === undefined
+        ? Number.POSITIVE_INFINITY
+        : turnNumber - lastAutoCompactTurn;
+    if (turnsSince < config.min_turns_between_auto) {
+        return { fire: false, reason: 'throttled' };
+    }
+    return { fire: true };
+}
+/**
+ * End-of-turn hook called by runTurn. Reads the gate, runs runCompact if
+ * the gate passes, surfaces a banner + the standard /compact result.
+ *
+ * Always swallows non-fatal errors — auto-compact must not regress the
+ * turn that just succeeded.
+ */
+export async function maybeAutoCompact(params) {
+    const { session, config, turnNumber, summarise } = params;
+    const emit = params.emit ?? ((line) => console.log(line));
+    const decision = shouldAutoCompact({
+        sessionInputTokens: session.usage?.input_tokens ?? 0,
+        turnNumber,
+        lastAutoCompactTurn: session.lastAutoCompactTurn,
+        config,
+    });
+    if (!decision.fire)
+        return;
+    // Banner BEFORE the work so the user understands the pause they're about
+    // to see. ~3s for a Haiku call on a long history.
+    emit('');
+    emit(chalk.yellow(`⚙  auto-compact: session crossed ${config.auto_threshold_tokens.toLocaleString()} input tokens`
+        + ` — summarising older turns to keep the next turn cheap.`));
+    try {
+        const result = await runCompact({
+            session,
+            summarise,
+            keepRecentTurns: config.keep_recent_turns,
+        });
+        if (result.performed) {
+            session.lastAutoCompactTurn = turnNumber;
+            // runCompact already saved the session inside its happy path, but we
+            // mutate one more field (the throttle marker) so re-save to capture it.
+            await saveSession(session);
+        }
+        emit(formatCompactResult(result, config.keep_recent_turns));
+    }
+    catch (err) {
+        // Defensive: never let a summariser blow take down the turn.
+        const msg = err instanceof Error ? err.message : String(err);
+        emit(chalk.yellow(`⚙  auto-compact bailed: ${msg}`));
+        emit(chalk.dim('   session left intact; /compact still available manually.'));
+    }
+}

package/dist/commands/compact.js

@@ -0,0 +1,265 @@
+/**
+ * `/compact` slash command — Phase 2 conversation hygiene (2026-05-16).
+ *
+ * Compacts older turns of the active session into a single Haiku-generated
+ * summary block so subsequent turns ingest ~5k tokens of context instead of
+ * 500k+. Built in response to live evidence from session 0618a42d where
+ * simple Q&A turns burned $3-8 each because of accumulated message history.
+ *
+ * Cost model: one Haiku call (typically ~0.01-0.05 USD) to save 80-90% on
+ * every subsequent turn until the session grows large again. Pays for
+ * itself after one follow-up turn.
+ *
+ * Quality boundary (set 2026-05-16 by Laeeq): summarisation is a mechanical
+ * read-and-condense task — Haiku 4.5 does this well. ABAP planning + code
+ * gen stay on Opus; only this one operation drops to Haiku.
+ *
+ * Safety:
+ *  - Before mutating session.messages, the prior shape is backed up to
+ *    `~/.cspeach/sessions/<id>.pre-compact-<timestamp>.json` so a rollback
+ *    is one file-rename away.
+ *  - The recent N user-prompt-anchored turns are kept verbatim — we never
+ *    summarise the most recent context.
+ *  - Tool-use / tool-result pairing is preserved by anchoring the cut on
+ *    user-prompt boundaries (where content is a string, not a tool_result
+ *    array).
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { sessionsDir } from '../config/paths.js';
+import { saveSession } from '../session/store.js';
+/** Keep this many recent user-prompt anchored turns verbatim. */
+export const KEEP_RECENT_TURNS = 5;
+/** Don't bother compacting if there's only a handful of older turns. */
+export const MIN_COMPACT_THRESHOLD = 3;
+/** Model used for summarisation — see quality boundary in the module doc. */
+export const COMPACTION_MODEL = 'claude-haiku-4-5';
+/**
+ * Decide which message indices to summarise vs keep verbatim.
+ *
+ * Strategy:
+ *  - Walk messages backwards looking for user prompts (content is a string,
+ *    not a tool_result array — that's the signal that a NEW user turn began)
+ *  - Mark the index of the Nth-most-recent user prompt as the "keep from
+ *    here on" boundary
+ *  - Everything before that boundary becomes the summarisation slice
+ *
+ * Returned `cutAt` is an exclusive end index for the summarisation slice —
+ * i.e. messages[0..cutAt-1] get summarised, messages[cutAt..] stay.
+ *
+ * If the session has fewer than KEEP_RECENT_TURNS user prompts, `cutAt` is
+ * 0 (nothing to compact). The caller bails in that case.
+ */
+export function planCompaction(messages, 
+/** Optional override — falls back to KEEP_RECENT_TURNS constant for back-compat. */
+keepRecentTurns = KEEP_RECENT_TURNS) {
+    let userPromptsSeen = 0;
+    let cutAt = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        // A user PROMPT (not a tool_result block) — content is a string.
+        if (msg.role === 'user' && typeof msg.content === 'string') {
+            userPromptsSeen++;
+            if (userPromptsSeen === keepRecentTurns) {
+                cutAt = i;
+                break;
+            }
+        }
+    }
+    return {
+        cutAt,
+        toSummarise: messages.slice(0, cutAt),
+        toKeep: messages.slice(cutAt),
+        userPromptCount: userPromptsSeen,
+    };
+}
+/**
+ * Build the Haiku prompt for summarising a session slice. Kept as a separate
+ * function so tests can assert on its shape and we can tune the prompt
+ * without touching the orchestration code.
+ *
+ * The output style we ask for is structured: decisions, objects, current
+ * state, open issues. That preserves the kind of context a follow-up turn
+ * actually needs while dropping the verbose tool-call chatter that drives
+ * the cost.
+ */
+export function buildSummarisationPrompt() {
+    return [
+        'You are compacting the older turns of a CSPeach (ABAP development CLI) conversation history.',
+        '',
+        'Your output replaces these turns in the session\'s context — the model will read your summary on the NEXT turn and continue working from it. So you must preserve everything the next turn needs to be useful.',
+        '',
+        'PRESERVE in your summary:',
+        '- Decisions made (architectural, naming, scope) with brief rationale',
+        '- SAP objects created or modified, with their types and active/inactive state',
+        '- Current state of any in-progress build (which phases done, which still open)',
+        '- Open issues, errors hit, deferred items',
+        '- Critical preferences/constraints the user set (model boundaries, naming conventions, etc.)',
+        '',
+        'DROP from your summary:',
+        '- Verbose tool-call args / results (just say "probed PACKAGE for existence" etc.)',
+        '- Repetitive content (the same class written 3 times — just the final shape)',
+        '- Intermediate failures already resolved',
+        '- TL;DR / Next sections from prior turns',
+        '- ASCII art separators, spinner output, footer rows',
+        '',
+        'OUTPUT FORMAT: a single markdown block with sections in this order:',
+        '1. ## Build state (one paragraph)',
+        '2. ## Decisions',
+        '3. ## Objects on SAP (table or bullet list)',
+        '4. ## Open / Deferred',
+        '5. ## Constraints set by user',
+        '',
+        'Aim for 1500-3000 tokens. Better to drop a detail than to bloat past 3000.',
+        '',
+        'The conversation history to compact follows below as JSON.',
+    ].join('\n');
+}
+/**
+ * Serialise a message array into a compact JSON string for the summariser
+ * to ingest. We send role + a flattened representation of content because
+ * the raw structure (tool_use blocks with partial_json mid-stream, etc.) is
+ * noisy and doesn't add summarisation signal.
+ */
+export function serialiseForSummariser(messages) {
+    const out = [];
+    for (const msg of messages) {
+        if (typeof msg.content === 'string') {
+            out.push({ role: msg.role, content: msg.content });
+        }
+        else if (Array.isArray(msg.content)) {
+            const flat = msg.content.map((b) => {
+                if (b == null)
+                    return '';
+                if (b.type === 'text')
+                    return b.text ?? '';
+                if (b.type === 'thinking')
+                    return `[thinking: ${(b.thinking ?? '').slice(0, 200)}]`;
+                if (b.type === 'tool_use')
+                    return `[tool_use: ${b.name}(${JSON.stringify(b.input ?? {}).slice(0, 300)})]`;
+                if (b.type === 'tool_result') {
+                    const content = typeof b.content === 'string' ? b.content : JSON.stringify(b.content);
+                    return `[tool_result: ${content.slice(0, 500)}${content.length > 500 ? '...' : ''}]`;
+                }
+                return '';
+            }).filter(Boolean).join('\n');
+            out.push({ role: msg.role, content: flat });
+        }
+    }
+    return JSON.stringify(out, null, 2);
+}
+/**
+ * Back up a session's pre-compact state to a sibling file so /compact is
+ * recoverable. Returns the backup file path.
+ */
+export async function backupBeforeCompact(session) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const dir = sessionsDir();
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${session.id}.pre-compact-${ts}.json`);
+    await fs.writeFile(filePath, JSON.stringify(session, null, 2), 'utf-8');
+    return filePath;
+}
+/**
+ * The compacted "synthesised earlier history" message that replaces the
+ * summarised slice in session.messages. Role=user because (a) Anthropic
+ * accepts multiple consecutive user messages, (b) putting it in user role
+ * makes it visually distinct from the model's prior assistant outputs, and
+ * (c) the explicit "context compacted by /compact" framing tells the next
+ * turn's model exactly what it's looking at.
+ */
+export function buildSummaryMessage(summary, droppedTurns) {
+    const ts = new Date().toISOString();
+    return {
+        role: 'user',
+        content: [
+            `[Context summary auto-generated by /compact at ${ts}.`,
+            `Original turns (${droppedTurns}) were summarised by ${COMPACTION_MODEL} to`,
+            `reduce cache cost on subsequent turns. The original session is backed up`,
+            `to ~/.cspeach/sessions/${'<session-id>'}.pre-compact-<timestamp>.json]`,
+            '',
+            summary,
+        ].join('\n'),
+    };
+}
+/**
+ * Top-level compact orchestration. Pure async function — caller wires it
+ * into the REPL slash dispatcher. Throws only on catastrophic IO failure
+ * (the summariser swallowing its own errors is fine because we never mutate
+ * session.messages until we have a valid summary in hand).
+ *
+ * Returns a result struct describing what happened. Caller renders the
+ * user-facing output.
+ */
+export async function runCompact(opts) {
+    const { session, summarise } = opts;
+    const keep = opts.keepRecentTurns ?? KEEP_RECENT_TURNS;
+    const plan = planCompaction(session.messages, keep);
+    // Bail if there's not enough older history to be worth compacting.
+    if (plan.userPromptCount < keep) {
+        return {
+            performed: false,
+            reason: `Session has ${plan.userPromptCount} user prompts; need at least ${keep + 1} for /compact to find anything to summarise.`,
+        };
+    }
+    if (plan.toSummarise.length < MIN_COMPACT_THRESHOLD) {
+        return {
+            performed: false,
+            reason: `Only ${plan.toSummarise.length} messages before the recent window — nothing meaningful to compact yet.`,
+        };
+    }
+    // Run the Haiku call FIRST. If it fails we don't touch the session.
+    let summary;
+    try {
+        summary = await summarise(plan.toSummarise);
+    }
+    catch (err) {
+        throw new Error(`Compaction summariser failed: ${err instanceof Error ? err.message : String(err)}. Session unchanged.`);
+    }
+    if (!summary || summary.trim().length === 0) {
+        throw new Error('Compaction summariser returned empty output. Session unchanged.');
+    }
+    // Back up the prior session state to a sibling file (one-shot rollback).
+    const backupPath = await backupBeforeCompact(session);
+    // Mutate session.messages: drop the summarised slice, prepend the synthesised
+    // summary message immediately before the kept tail. The session retains its
+    // FIRST user message intact only if it was already in the toKeep slice —
+    // which it will be unless the session is very long. (For very long sessions
+    // we accept losing the original first prompt because the summary should
+    // mention what the goal was.)
+    const summaryMsg = buildSummaryMessage(summary, plan.toSummarise.length);
+    session.messages = [summaryMsg, ...plan.toKeep];
+    await saveSession(session);
+    return {
+        performed: true,
+        droppedTurns: plan.toSummarise.length,
+        keptTurns: plan.toKeep.length,
+        summaryTokens: Math.ceil(summary.length / 4), // rough — 4 chars per token
+        backupPath,
+    };
+}
+/**
+ * Format the result of a compact run for terminal display. Separate so
+ * tests can assert on shape and the REPL just renders.
+ */
+export function formatCompactResult(result, 
+/** Optional — falls back to the legacy constant for back-compat. */
+keepRecentTurns = KEEP_RECENT_TURNS) {
+    if (!result.performed) {
+        return chalk.dim(`/compact: ${result.reason ?? 'nothing to do'}`);
+    }
+    const lines = [
+        '',
+        chalk.bold('/compact complete'),
+        chalk.dim(`  dropped:   ${result.droppedTurns} messages`),
+        chalk.dim(`  kept:      ${result.keptTurns} messages (most recent ${keepRecentTurns} user turns intact)`),
+        chalk.dim(`  summary:   ~${result.summaryTokens?.toLocaleString()} tokens`),
+        chalk.dim(`  backup:    ${result.backupPath}`),
+        '',
+        chalk.green('Next turn\'s context is now roughly summary-size instead of full history.'),
+        chalk.dim('Heads-up: the very next turn rebuilds the prompt cache (one-off cost), then turns after that are cheap again.'),
+        '',
+    ];
+    return lines.join('\n');
+}

package/dist/commands/cost.js

@@ -0,0 +1,56 @@
+/**
+ * `/cost` slash command — Phase 1 cost tracking (2026-05-16).
+ *
+ * Reads the current session's per-turn cost log and prints a human-readable
+ * breakdown to the REPL: total spend, per-category tokens, and per-model
+ * split (will matter once Phase 2 lands and a single session crosses
+ * Haiku + Sonnet + Opus).
+ *
+ * No mutation, no network. Safe to run anytime.
+ */
+import chalk from 'chalk';
+import { readCostLog, summarise } from '../cost/cost-log.js';
+import { formatCost } from '../cost/pricing.js';
+export async function runCostCommand(sessionId) {
+    const entries = await readCostLog(sessionId);
+    if (entries.length === 0) {
+        console.log('');
+        console.log(chalk.dim('No cost data yet for this session. Run a turn first.'));
+        console.log('');
+        return;
+    }
+    const s = summarise(entries);
+    // Header
+    console.log('');
+    console.log(chalk.bold(`Session cost so far: ${formatCost(s.totalCost)}`) + chalk.dim(`   (${s.turns} turn${s.turns === 1 ? '' : 's'})`));
+    // Token breakdown
+    console.log('');
+    console.log(chalk.dim('Tokens:'));
+    console.log(`  input         ${s.totalTokens.input.toLocaleString().padStart(12)}`);
+    console.log(`  output        ${s.totalTokens.output.toLocaleString().padStart(12)}`);
+    console.log(`  cache read    ${s.totalTokens.cacheRead.toLocaleString().padStart(12)}`);
+    console.log(`  cache create  ${s.totalTokens.cacheCreate.toLocaleString().padStart(12)}`);
+    // Per-model split (Phase 2 will make this interesting)
+    if (s.byModel.length > 1) {
+        console.log('');
+        console.log(chalk.dim('By model:'));
+        for (const m of s.byModel) {
+            console.log(`  ${m.model.padEnd(24)} ${m.turns} turn${m.turns === 1 ? '' : 's'}   ${formatCost(m.cost)}`);
+        }
+    }
+    else if (s.byModel[0]) {
+        console.log('');
+        console.log(chalk.dim(`Model: ${s.byModel[0].model}`));
+    }
+    // Recent turns — last 5 lines, most recent first
+    const recent = entries.slice(-5).reverse();
+    console.log('');
+    console.log(chalk.dim(`Recent turns (last ${recent.length}):`));
+    for (const e of recent) {
+        const tok = (e.tokens.input + e.tokens.output).toLocaleString();
+        console.log(`  turn ${String(e.turn).padStart(3)}   ${tok.padStart(10)} tok   ${formatCost(e.cost)}`);
+    }
+    console.log('');
+    console.log(chalk.dim(`Detailed JSONL: ~/.cspeach/sessions/${sessionId}-cost.jsonl`));
+    console.log('');
+}

package/dist/commands/help.js

@@ -61,33 +61,40 @@ function wrapDescription(desc, width, maxLines) {
  * Cyan category headings, bold skill names, default-color descriptions.
  * Descriptions wrap to MAX_DESC_LINES lines max, aligned to the name column.
  */
-export function printHelp() {
+/**
+ * Phase D5 (2026-05-17) — accepts an optional emit callback so Ink mode
+ * can route output through chunkEmitter instead of console.log (which
+ * corrupts the React frame). Default keeps the classic-mode behaviour.
+ */
+export function printHelp(emit = (s) => console.log(s)) {
     const termWidth = process.stdout.columns ?? DEFAULT_TERM_WIDTH;
     const descWidth = Math.max(MIN_DESC_WIDTH, termWidth - NAME_COL_WIDTH);
     const continuationIndent = ' '.repeat(NAME_COL_WIDTH);
-    console.log('');
+    emit('');
     for (const category of CATEGORY_ORDER) {
         const skills = SKILL_CATALOG.filter((s) => s.category === category);
         if (skills.length === 0)
             continue;
-        console.log(chalk.cyan.bold(category));
+        emit(chalk.cyan.bold(category));
         for (const skill of skills) {
             const nameCol = ('/' + skill.name).padEnd(NAME_COL_PAD);
             const descLines = wrapDescription(skill.description, descWidth, MAX_DESC_LINES);
             const firstLine = descLines[0] ?? '';
-            console.log(`  ${chalk.bold(nameCol)} ${firstLine}`);
+            emit(`  ${chalk.bold(nameCol)} ${firstLine}`);
             for (let j = 1; j < descLines.length; j++) {
-                console.log(`${continuationIndent}${descLines[j]}`);
+                emit(`${continuationIndent}${descLines[j]}`);
             }
         }
-        console.log('');
+        emit('');
     }
-    console.log(chalk.cyan.bold('Shortcuts'));
-    console.log(`  ${chalk.bold('/help'.padEnd(NAME_COL_PAD))} This screen`);
-    console.log(`  ${chalk.bold('/skills'.padEnd(NAME_COL_PAD))} Same as /help`);
-    console.log(`  ${chalk.bold('/ui [auto|ink|classic]'.padEnd(NAME_COL_PAD))} View or change UI rendering mode`);
-    console.log(`  ${chalk.bold('/reroute <skill>'.padEnd(NAME_COL_PAD))} Re-run your last prompt with a different skill`);
-    console.log(`  ${chalk.bold('/new'.padEnd(NAME_COL_PAD))} End the current Q&A chain — next prompt is classified fresh`);
-    console.log(`  ${chalk.bold('/exit'.padEnd(NAME_COL_PAD))} Quit CSPeach`);
-    console.log('');
+    emit(chalk.cyan.bold('Shortcuts'));
+    emit(`  ${chalk.bold('/help'.padEnd(NAME_COL_PAD))} This screen`);
+    emit(`  ${chalk.bold('/skills'.padEnd(NAME_COL_PAD))} Same as /help`);
+    emit(`  ${chalk.bold('/ui [auto|ink|classic]'.padEnd(NAME_COL_PAD))} View or change UI rendering mode`);
+    emit(`  ${chalk.bold('/reroute <skill>'.padEnd(NAME_COL_PAD))} Re-run your last prompt with a different skill`);
+    emit(`  ${chalk.bold('/new'.padEnd(NAME_COL_PAD))} End the current Q&A chain — next prompt is classified fresh`);
+    emit(`  ${chalk.bold('/cost'.padEnd(NAME_COL_PAD))} Show this session's API spend so far ($ + token breakdown)`);
+    emit(`  ${chalk.bold('/compact'.padEnd(NAME_COL_PAD))} Summarise older turns into a compact context block — cuts subsequent turn cost by 80-90%`);
+    emit(`  ${chalk.bold('/exit'.padEnd(NAME_COL_PAD))} Quit CSPeach`);
+    emit('');
 }

package/dist/config/loader.js

@@ -24,7 +24,42 @@ const DEFAULT_CONFIG = {
     write_mode: 'approval-gated',
     // Default `managed` — lowest-friction entry point; uses the cspeach.dev proxy.
     llm: { mode: 'managed' },
+    // Defaults tuned 2026-05-16 from session 0618a42d evidence — see CompactConfig doc.
+    compact: {
+        keep_recent_turns: 5,
+        auto_enabled: true,
+        auto_threshold_tokens: 1_000_000,
+        min_turns_between_auto: 5,
+    },
 };
+/**
+ * Coerce a possibly-bad `compact` block from disk into a safe CompactConfig.
+ * - missing/undefined → defaults
+ * - wrong type → defaults
+ * - out-of-range numbers → clamped to sane bounds (keep_recent_turns 1..50,
+ *   auto_threshold_tokens 10_000..10_000_000, min_turns_between_auto 1..100)
+ *
+ * Defensive because TOML hand-editing makes typos likely and we never want
+ * a config typo to lock the user out of the REPL.
+ */
+function sanitiseCompact(raw) {
+    const d = DEFAULT_CONFIG.compact;
+    if (!raw || typeof raw !== 'object')
+        return { ...d };
+    const r = raw;
+    const intInRange = (v, fallback, lo, hi) => {
+        if (typeof v !== 'number' || !Number.isFinite(v))
+            return fallback;
+        const i = Math.floor(v);
+        return Math.min(hi, Math.max(lo, i));
+    };
+    return {
+        keep_recent_turns: intInRange(r.keep_recent_turns, d.keep_recent_turns, 1, 50),
+        auto_enabled: typeof r.auto_enabled === 'boolean' ? r.auto_enabled : d.auto_enabled,
+        auto_threshold_tokens: intInRange(r.auto_threshold_tokens, d.auto_threshold_tokens, 10_000, 10_000_000),
+        min_turns_between_auto: intInRange(r.min_turns_between_auto, d.min_turns_between_auto, 1, 100),
+    };
+}
 export async function loadConfig() {
     try {
         const raw = await fs.readFile(configFile(), 'utf-8');
@@ -52,6 +87,10 @@ export async function loadConfig() {
             llm: { ...DEFAULT_CONFIG.llm, ...(parsed.llm ?? {}) },
             classifier: { ...DEFAULT_CONFIG.classifier, ...(parsed.classifier ?? {}) },
             ui: { ...DEFAULT_CONFIG.ui, ...(parsed.ui ?? {}) },
+            // Deep-merge `compact` so a user config that only overrides one
+            // field (e.g. just `keep_recent_turns = 10`) still gets the four
+            // unspecified defaults — and a typo'd field falls through harmlessly.
+            compact: sanitiseCompact(parsed.compact),
             shell_exec: parsed.shell_exec === undefined ? undefined : { allow },
         };
     }