@cspeach/cli 1.1.19 → 1.1.20

package/dist/agent/anthropic-provider.js

@@ -12,24 +12,28 @@ import { createManagedSkillSource } from '../skills/source-managed.js';
 import { CLI_VERSION } from '../lib/version.js';
 export function createManagedProvider(cfg, getBearer) {
     const skillSource = createManagedSkillSource(cfg, getBearer);
+    // Headers every managed request carries (the real call and the keepalive
+    // ping alike, so the proxy's enforcement / version gate pick the same model).
+    const defaultHeaders = async () => {
+        const bearer = await getBearer();
+        const device = await getDeviceFingerprint();
+        return {
+            'authorization': `Bearer ${bearer}`,
+            'anthropic-beta': 'compact-2026-01-12',
+            'x-device-machine-id': device.machineId,
+            'x-device-hostname': device.hostname,
+            'User-Agent': `cspeach/${CLI_VERSION}`,
+        };
+    };
     return {
         name: 'anthropic-managed',
         mode: 'managed',
         skillSource,
         async createStream(params, options = {}) {
-            const bearer = await getBearer();
-            const device = await getDeviceFingerprint();
-            const cliVersion = CLI_VERSION;
             const sdk = new Anthropic({
                 apiKey: 'proxy-bearer-auth', // ignored by our proxy; SDK requires non-empty
                 baseURL: cfg.proxy_url.replace(/\/$/, '') + '/',
-                defaultHeaders: {
-                    'authorization': `Bearer ${bearer}`,
-                    'anthropic-beta': 'compact-2026-01-12',
-                    'x-device-machine-id': device.machineId,
-                    'x-device-hostname': device.hostname,
-                    'User-Agent': `cspeach/${cliVersion}`,
-                },
+                defaultHeaders: await defaultHeaders(),
             });
             // Per-call headers (e.g. X-CSForge-Skill) passed as second argument to the SDK.
             // The SDK forwards them alongside defaultHeaders on this specific request.
@@ -41,6 +45,22 @@ export function createManagedProvider(cfg, getBearer) {
                 sdkOptions.signal = options.signal;
             return sdk.messages.stream(params, Object.keys(sdkOptions).length > 0 ? sdkOptions : undefined);
         },
+        // Task 15 — POST /v1/keepalive (Task 14 route): the proxy rebuilds the
+        // upstream request with the same code as /v1/messages and sends it with
+        // max_tokens 0. Same headers as the real call; the proxy mints its own
+        // request id. Any non-2xx rejects (the keepalive timer stops this wait).
+        async keepalive(params, options = {}) {
+            const r = await fetch(`${cfg.proxy_url.replace(/\/$/, '')}/v1/keepalive`, {
+                method: 'POST',
+                headers: { ...(await defaultHeaders()), ...(options.headers ?? {}), 'content-type': 'application/json' },
+                body: JSON.stringify(params),
+                signal: AbortSignal.timeout(20_000),
+            });
+            // Drain the small JSON body so the connection is released.
+            await r.text().catch(() => '');
+            if (!r.ok)
+                throw Object.assign(new Error(`keepalive HTTP ${r.status}`), { status: r.status });
+        },
         async healthCheck() {
             try {
                 const bearer = await getBearer();

package/dist/agent/cache-keepalive.js

@@ -0,0 +1,162 @@
+/** Ping cadence: under the 300 s cache TTL with 30 s of slack. */
+export const KEEPALIVE_INTERVAL_MS = 270_000;
+/**
+ * Deep copy of a request, so neither the loop's later pushes nor any in-place
+ * edit of an earlier message can change what a ping re-sends.
+ */
+export function snapshotParams(params) {
+    try {
+        return structuredClone(params);
+    }
+    catch {
+        return JSON.parse(JSON.stringify(params));
+    }
+}
+/**
+ * True when the API cached part of the prompt (read or wrote). A prompt under
+ * the model's minimum cacheable size reports zero for both, and pinging it
+ * would buy nothing.
+ */
+export function isCacheablePrompt(usage) {
+    if (!usage)
+        return false;
+    return (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0) > 0;
+}
+export class CacheKeepalive {
+    opts;
+    timer = null;
+    generation = 0;
+    sent = 0;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Pings sent so far by this instance. */
+    get pings() {
+        return this.sent;
+    }
+    /**
+     * Start (or restart) the timer for one wait. `params` must already be a
+     * snapshot. Only the headers of `options` are forwarded — never the turn's
+     * abort signal (a ping outlives nothing and is cancelled by disarm).
+     */
+    arm(params, options = {}) {
+        this.disarm();
+        if (typeof this.opts.provider.keepalive !== 'function')
+            return;
+        if (this.sent >= this.opts.maxPings)
+            return;
+        const callOptions = options.headers ? { headers: { ...options.headers } } : {};
+        this.schedule(this.generation, params, callOptions);
+    }
+    /** Cancel the pending ping (an in-flight one finishes but does not re-arm). */
+    disarm() {
+        this.generation++;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    schedule(gen, params, options) {
+        const t = setTimeout(() => { void this.fire(gen, params, options); }, this.opts.intervalMs ?? KEEPALIVE_INTERVAL_MS);
+        // Never keep the process alive for a ping.
+        t.unref?.();
+        this.timer = t;
+    }
+    async fire(gen, params, options) {
+        this.timer = null;
+        if (gen !== this.generation)
+            return;
+        const n = ++this.sent;
+        let failed;
+        let ok = true;
+        try {
+            await this.opts.provider.keepalive(params, options);
+        }
+        catch (err) {
+            ok = false;
+            failed = err;
+        }
+        try {
+            this.opts.onPing?.(n, ok ? undefined : failed);
+        }
+        catch {
+            // an observer must never break the timer
+        }
+        if (!ok)
+            return; // stop pinging this wait
+        if (gen !== this.generation)
+            return; // disarmed while the ping was in flight
+        if (this.sent >= this.opts.maxPings)
+            return;
+        this.schedule(gen, params, options);
+    }
+}
+// Keyed by the session object: never persisted with the session, and a
+// subagent's child session keeps its own record.
+const lastRequests = new WeakMap();
+export function recordLastRequest(session, rec) {
+    const stored = { ...rec, firstMessage: session.messages[0], length: session.messages.length };
+    lastRequests.set(session, stored);
+    return stored;
+}
+/**
+ * The session's last request, or undefined when there was none or the history
+ * no longer extends it (compaction, a plan-resume reset): pinging a prefix the
+ * next call will not send would warm the wrong cache.
+ */
+export function lastRequestFor(session) {
+    const rec = lastRequests.get(session);
+    if (!rec)
+        return undefined;
+    if (session.messages.length < rec.length || session.messages[0] !== rec.firstMessage)
+        return undefined;
+    return rec;
+}
+// Task 19 — when a keepalive ping last kept this session's prompt cache warm.
+// `last_request_at` is stamped only by real model calls, so without this an
+// idle session kept warm by pings would look cold to the cold-cache prune and
+// have its (still cached) history rewritten. In-process only: no ping runs
+// while the CLI is closed.
+const cacheTouched = new WeakMap();
+/** Record a successful keepalive ping for `session` (default: now). */
+export function noteCacheTouched(session, at = Date.now()) {
+    cacheTouched.set(session, at);
+}
+/** Epoch ms of the last successful keepalive ping for `session`, if any. */
+export function cacheTouchedAt(session) {
+    return cacheTouched.get(session);
+}
+/**
+ * The REPL's between-turns keepalive: armed after a turn ends, disarmed on the
+ * next submit and on exit. Each idle period gets its own `idle_pings` budget,
+ * but only for a NEW request — a slash command that made no model call does
+ * not restart the budget, so an abandoned session stops after ~18 min
+ * (4 × 270 s) and never pings forever.
+ */
+export class IdleKeepalive {
+    opts;
+    current = null;
+    lastArmed;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    armAfterTurn(session) {
+        const rec = lastRequestFor(session);
+        if (!rec || !rec.cacheable || rec === this.lastArmed)
+            return;
+        this.disarm();
+        this.lastArmed = rec;
+        this.current = new CacheKeepalive({
+            provider: this.opts.provider,
+            maxPings: this.opts.maxPings(),
+            // Task 19 — a successful idle ping keeps the cache warm (cold prune).
+            onPing: (_n, err) => { if (err === undefined)
+                noteCacheTouched(session); },
+        });
+        this.current.arm(rec.params, rec.options);
+    }
+    disarm() {
+        this.current?.disarm();
+        this.current = null;
+    }
+}

package/dist/agent/cold-prune.js

@@ -0,0 +1,116 @@
+/**
+ * Task 19 (model control, 2026-09-27, owner decision 7) — cold-cache prune.
+ *
+ * The prompt cache lives 300 s. Once it has expired, the next call re-writes
+ * the WHOLE history into the cache anyway, so rewriting old history at that
+ * moment costs no cache it would otherwise have read. This elides the content
+ * of old `tool_result` blocks (source dumps, SQL rows, file reads — the bulk of
+ * a long session) and so shrinks that cache write and every later read.
+ *
+ * Default OFF: runs only with `CSPEACH_COLD_PRUNE=on` (the owner first). Runs
+ * once at turn start, before the first createStream, and only when the cache
+ * is cold: `last_request_at` (the last real model call) and the last
+ * successful keepalive ping are both more than 300 s old.
+ *
+ * Valid history is kept: only `tool_result.content` changes; the block, its
+ * `tool_use_id` pairing and `is_error` stay. The last `keepRecentUserTurns`
+ * user turns are never touched. Idempotent: an elided result is recognised
+ * and left alone.
+ *
+ * Thinking (fix round 1): the API binds each thinking block to the exact
+ * prefix that produced it (Opus 5.5 block binding), so every assistant message
+ * AFTER the first elided result loses its thinking blocks — the same
+ * stripThinking /compact applies (a thinking-only message keeps a placeholder
+ * text, never empty content). Messages before that point keep theirs.
+ */
+import { isUserPrompt } from '../session/user-prompt.js';
+import { cacheTouchedAt } from './cache-keepalive.js';
+import { stripThinking } from '../commands/compact.js';
+/** The cache TTL: older than this since the last call ⇒ the cache is cold. */
+export const COLD_PRUNE_AFTER_MS = 300_000;
+/** User turns (typed prompts) kept intact at the end of the history. */
+export const COLD_PRUNE_KEEP_USER_TURNS = 2;
+const ELIDED_RE = /^\[result elided at cold start — \d+ chars\]$/;
+function elidedMarker(chars) {
+    return `[result elided at cold start — ${chars} chars]`;
+}
+/** Characters a tool_result's content carries (text, else its JSON). */
+function contentChars(content) {
+    if (typeof content === 'string')
+        return content.length;
+    if (!Array.isArray(content))
+        return 0;
+    let n = 0;
+    for (const b of content) {
+        if (b?.type === 'text' && typeof b.text === 'string')
+            n += b.text.length;
+        else
+            n += JSON.stringify(b ?? null).length;
+    }
+    return n;
+}
+/**
+ * Replace the content of every `tool_result` that sits before the last
+ * `keepRecentUserTurns` user prompts with a one-line marker. Mutates
+ * `messages` in place; returns how many results were elided (0 = untouched).
+ */
+export function pruneStaleToolResults(messages, opts) {
+    const keep = Math.max(0, Math.floor(opts.keepRecentUserTurns));
+    const promptIdx = [];
+    messages.forEach((m, i) => { if (isUserPrompt(m))
+        promptIdx.push(i); });
+    if (promptIdx.length <= keep)
+        return 0;
+    const cut = keep === 0 ? messages.length : promptIdx[promptIdx.length - keep];
+    let elided = 0;
+    let firstElided = -1;
+    for (let i = 0; i < cut; i++) {
+        const m = messages[i];
+        if (m.role !== 'user' || !Array.isArray(m.content))
+            continue;
+        for (const block of m.content) {
+            if (block?.type !== 'tool_result')
+                continue;
+            const content = block.content;
+            if (typeof content === 'string' && ELIDED_RE.test(content))
+                continue;
+            const chars = contentChars(content);
+            const marker = elidedMarker(chars);
+            if (chars <= marker.length)
+                continue; // nothing to save
+            block.content = marker;
+            elided++;
+            if (firstElided < 0)
+                firstElided = i;
+        }
+    }
+    if (firstElided >= 0) {
+        for (let i = firstElided + 1; i < messages.length; i++) {
+            messages[i] = stripThinking(messages[i]);
+        }
+    }
+    return elided;
+}
+/**
+ * The turn-start gate: prune only with `CSPEACH_COLD_PRUNE=on` and a cold
+ * cache. Returns how many results were elided (0 when the gate refused).
+ */
+export function maybeColdPrune(session, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (env.CSPEACH_COLD_PRUNE?.trim().toLowerCase() !== 'on')
+        return 0;
+    if (typeof session.last_request_at !== 'string')
+        return 0;
+    const lastCall = Date.parse(session.last_request_at);
+    if (!Number.isFinite(lastCall))
+        return 0;
+    const lastWarm = Math.max(lastCall, cacheTouchedAt(session) ?? 0);
+    const now = opts.now ?? Date.now();
+    if (now - lastWarm <= COLD_PRUNE_AFTER_MS)
+        return 0;
+    const pruned = pruneStaleToolResults(session.messages, { keepRecentUserTurns: COLD_PRUNE_KEEP_USER_TURNS });
+    // The recorded context size described the unpruned history.
+    if (pruned > 0)
+        delete session.last_context_tokens;
+    return pruned;
+}