From ffcf00817b4a834a52a53e2615908d51aea90d48 Mon Sep 17 00:00:00 2001 From: Darknode-Official Date: Wed, 11 Nov 2026 08:00:10 -0800 Subject: [PATCH] /cheap: keep the 1-hour prompt cache warm while you are away On a 1-hour cache, returning after the hour rewrites the whole context at the write rate (about 80x a read on Fable). With /cheap on, Nexus now sends a one-turn ping in the last 4 minutes before expiry, which reads the cache and restarts the hour. - The ping resumes the session with --fork-session --no-session-persistence --max-turns 1, so no transcript is written and the conversation is unchanged. It reuses the last real launch (model, effort, system prompt, skill overrides, MCP config), so it hits the same cached prefix. - Hooks are off for the ping only; they are not part of the cached prefix. - Only on a 1h TTL, with 20k+ context, idle, and within 6h of the last message. A 5-minute cache is cheaper to rebuild than to keep warm. - Priced from the ping's own usage: on a resumed run total_cost_usd and modelUsage are the session's running totals. - /cheap status shows the refresh count and their cost. Measured on Haiku: the ping read the full ~27k context from cache, wrote 50 tokens, left the original transcript untouched and saved no fork. 14-day replay of real traffic at Fable rates: about $43 net saved. --- darknode.js | 25 +++++++++++++++++++------ lib/nexus/cheap.js | 29 +++++++++++++++++++++++++---- test/run.js | 11 +++++++++++ 3 files changed, 55 insertions(+), 10 deletions(-) diff --git a/darknode.js b/darknode.js index 7471736..eb2255a 100755 --- a/darknode.js +++ b/darknode.js @@ -1983,7 +1983,8 @@ function runClaudeStream(prompt, cwd, cont, h, ctl, opts) { if (opts.maxBudgetUsd) args.push("--max-budget-usd", String(opts.maxBudgetUsd)); if (opts.maxTurns) args.push("--max-turns", String(opts.maxTurns)); if (opts.disallow && opts.disallow.length) args.push("--disallowed-tools", ...opts.disallow); - args.push(...Cheap.launchFlags(opts.cheap, opts.skillOverrides)); + args.push(...Cheap.launchFlags(opts.cheap, opts.skillOverrides, opts.keepWarm)); + if (opts.keepWarm) args.push(...Cheap.keepWarmFlags()); // one turn on an unsaved fork: reads the cache, leaves the conversation as it was if (opts.mcpConfigPath) args.push("--mcp-config", opts.mcpConfigPath); // give claude the Nexus ask bridge (+ any .nexus/mcp.json servers); no --strict so claude keeps its own servers too const env = opts.small ? Object.assign({}, process.env, { ANTHROPIC_SMALL_FAST_MODEL: opts.small, CLAUDE_CODE_BG_CLASSIFIER_MODEL: opts.small }) : process.env; const cp = _cp.spawn("claude", args, { cwd, env, detached: process.platform !== "win32" }); // own process group so an interrupt kills claude and its tool subprocesses @@ -2929,13 +2930,13 @@ function nexusTui(engine, cwd, nexusMd, autoResume, launch) { if (launch.lean) lean = true; // --lean, this launch only if (launch.yes) transcript.push({ role: "system", text: "-y / --skip-permissions applies to one-shot runs; here the permission mode is shift+tab (accept edits · plan · bypass)." }); const READONLY_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit", "Bash"]; // disallowed to enforce read-only (plan mode / /bench) - const impact = { localTurns: 0, cloudTurns: 0, localTok: 0, cloudInTok: 0, cloudOutTok: 0, cloudCost: 0, ctxSavedTok: 0, coworkSaved: 0, delegated: 0, cachedHits: 0, cachedSaved: 0, squeezeTok: 0, repeatTok: 0, memoTok: 0, sideSkipped: 0 }; // Impact Receipt tallies + const impact = { localTurns: 0, cloudTurns: 0, localTok: 0, cloudInTok: 0, cloudOutTok: 0, cloudCost: 0, ctxSavedTok: 0, coworkSaved: 0, delegated: 0, cachedHits: 0, cachedSaved: 0, squeezeTok: 0, repeatTok: 0, memoTok: 0, sideSkipped: 0, keepWarm: 0, keepWarmCost: 0 }; // Impact Receipt tallies const editUndo = require("./lib/nexus/edit-undo").createEditUndo(); // undo_edit: the agent's own per-file changes this session const SyntaxGate = require("./lib/nexus/syntax-gate"); // after an edit: warn if it introduced a syntax error (settings.syntaxGate) const sessStart = Date.now(); // wall-clock start of this TUI session (dashboard uptime) const sessFiles = new Set(); // every repo-relative file the agent touched this session (for the dashboard) const toolUse = Object.create(null); // tool name -> call count this session (for the dashboard) - let cheapPrev = settingsStore.getSaved("cheapPrev") || null, modelHold = null; // settings to restore on /cheap off; a model switch waiting for its confirming repeat + let cheapPrev = settingsStore.getSaved("cheapPrev") || null, modelHold = null, lastClaudeOpts = null, lastAskAt = 0, warming = false; // lastClaudeOpts/lastAskAt/warming: keep-warm reuses the last real launch exactly; settings to restore on /cheap off; a model switch waiting for its confirming repeat let cacheOn = !!S.cache; // response cache: serve exact-repeat read-only answers for free (off by default — opt in with /cache on) let cowork = { on: false, strong: "", weak: "", weakKind: "claude" }; // strong codes, weak does cheap work; weakKind: claude|ollama(local, free) const auxModel = () => (cowork.on && cowork.weakKind === "claude" && engine === "claude") ? cowork.weak : undefined; // weak CLAUDE model for aux calls @@ -4126,7 +4127,18 @@ function nexusTui(engine, cwd, nexusMd, autoResume, launch) { const revealing = () => { const b = activeBlock || cur(); if (!b || !b.items) return false; return b.items.some((it) => it.type === "text" && it.shown < it.full.length); }; const startTick = () => { if (tick) return; tick = setInterval(() => { const b = activeBlock || cur(); if (b && b.items) for (const it of b.items) if (it.type === "text" && it.shown < it.full.length) { let ns = Math.min(it.full.length, it.shown + Math.max(2, Math.ceil((it.full.length - it.shown) / 22))); const cc = it.full.charCodeAt(ns - 1); if (cc >= 0xD800 && cc <= 0xDBFF && ns < it.full.length) ns++; it.shown = ns; } render(); if (!busy && !revealing() && !compact.on) { clearInterval(tick); tick = null; } }, 45); }; // idle refresh for the prompt-cache chip: re-render only when its text changes (minute steps, then seconds in the last minute) - let lastWarmChip = ""; const warmTimer = setInterval(() => { if (busy || engine !== "claude" || !cacheWarm.lastAt) return; const c = CacheWarm.chip(CacheWarm.cacheState({ lastAt: cacheWarm.lastAt, ttl: cacheWarm.ttl, now: Date.now() })); if (c !== lastWarmChip) { lastWarmChip = c; render(); } }, 5000); if (warmTimer.unref) warmTimer.unref(); + // /cheap keep-warm: refresh a 1-hour cache just before it expires while you are away + const keepWarm = () => { + if (warming || !lastClaudeOpts || !Cheap.keepWarmDue({ cheap: !!(cacheOn && tightEdits && cheapSide), engine, sid: claudeSid, busy, lastAt: cacheWarm.lastAt, ttl: cacheWarm.ttl, now: Date.now(), lastHumanAt: lastAskAt, ctxTok: sess.ctxUsed })) return; + warming = true; const sid = claudeSid, model = sess.resolvedModel || sess.model; + runClaudeStream(Cheap.KEEP_WARM_PROMPT, cwd, false, { onResult: (ev) => { + if (claudeSid !== sid) return; // the chat was cleared meanwhile + const u = ev.usage || {}, c = costOf(model, usageBuckets(u)); // usage is this run's own; modelUsage and total_cost_usd carry the resumed session's running totals + addUsage(null, u, model); sess.cost += c; impact.keepWarmCost += c; + impact.keepWarm++; + } }, null, Object.assign({}, lastClaudeOpts, { resume: sid, keepWarm: true, maxBudgetUsd: undefined })).then(() => { warming = false; render(); }, () => { warming = false; }); + }; + let lastWarmChip = ""; const warmTimer = setInterval(() => { if (busy || engine !== "claude" || !cacheWarm.lastAt) return; keepWarm(); const c = CacheWarm.chip(CacheWarm.cacheState({ lastAt: cacheWarm.lastAt, ttl: cacheWarm.ttl, now: Date.now() })); if (c !== lastWarmChip) { lastWarmChip = c; render(); } }, 5000); if (warmTimer.unref) warmTimer.unref(); // Flatten the kept transcript tail into a short plain-text summary, so a // claude turn that has just dropped --continue still knows what came before. // User lines and the model's own answers only — no tool spew, capped so the @@ -4439,6 +4451,7 @@ function nexusTui(engine, cwd, nexusMd, autoResume, launch) { const _resumeSid = (engine === "claude" && claudeSid) ? claudeSid : undefined; // always resume OUR session by id: bare --continue takes the folder's newest Claude session (a one-shot, or the user's own `claude` run) oneShotRan = false; if (engine === "claude") { + lastAskAt = Date.now(); runClaudeStream(promptText, cwd, cont, { onInit: (ev) => { if (ev.model) sess.model = ev.model; if (ev.session_id) claudeSid = ev.session_id; }, onRateLimit: (info) => { rate = info; }, @@ -4474,7 +4487,7 @@ function nexusTui(engine, cwd, nexusMd, autoResume, launch) { addUsage(_mu, u, sess.resolvedModel || sess.model); const mu = ev.modelUsage && ev.modelUsage[sess.model]; if (mu && mu.contextWindow) sess.ctxWindow = mu.contextWindow; }, - }, ctl, { resume: _resumeSid, model: cowork.on ? cowork.strong : ((sess.userModel && sess.model && sess.model !== engine) ? sess.model : undefined), small: cowork.on && cowork.weakKind === "claude" ? cowork.weak : undefined, effort: effort || undefined, cheap: !!(cacheOn && tightEdits && cheapSide), skillOverrides: cacheOn && tightEdits && cheapSide ? Cheap.overridesFor(NHOME, cwd) : null, appendSystemPrompt: require("./lib/nexus/bg-cutoff").HOST_NOTE + "\n" + ((nexusMd ? "Project (.nexus/NEXUS.md):\n" + nexusMd.slice(0, 1000) : "") + (tightEdits ? "\n" + TIGHT_DIR : "") + (minimizeCalls ? "\nMinimize tool calls: chain shell commands, read only needed lines, never re-read after write. 2-5 calls for simple tasks." : "") + (lean ? "\nTerse output, no preamble." : "") + (styleDir(style) ? "\n" + styleDir(style) : "") + (hack ? "\n" + HACK_DIR : "") + policyPrompt() + ASK_ENGINE_NOTE) || undefined, mcpConfigPath: engineMcpConfigPath(), fallbackModel: fallback || undefined, maxBudgetUsd: costCap ? Math.max(0.01, costCap - sess.cost).toFixed(2) : undefined, disallow: mode === 2 ? READONLY_TOOLS : undefined }).then(finish); + }, ctl, lastClaudeOpts = { resume: _resumeSid, model: cowork.on ? cowork.strong : ((sess.userModel && sess.model && sess.model !== engine) ? sess.model : undefined), small: cowork.on && cowork.weakKind === "claude" ? cowork.weak : undefined, effort: effort || undefined, cheap: !!(cacheOn && tightEdits && cheapSide), skillOverrides: cacheOn && tightEdits && cheapSide ? Cheap.overridesFor(NHOME, cwd) : null, appendSystemPrompt: require("./lib/nexus/bg-cutoff").HOST_NOTE + "\n" + ((nexusMd ? "Project (.nexus/NEXUS.md):\n" + nexusMd.slice(0, 1000) : "") + (tightEdits ? "\n" + TIGHT_DIR : "") + (minimizeCalls ? "\nMinimize tool calls: chain shell commands, read only needed lines, never re-read after write. 2-5 calls for simple tasks." : "") + (lean ? "\nTerse output, no preamble." : "") + (styleDir(style) ? "\n" + styleDir(style) : "") + (hack ? "\n" + HACK_DIR : "") + policyPrompt() + ASK_ENGINE_NOTE) || undefined, mcpConfigPath: engineMcpConfigPath(), fallbackModel: fallback || undefined, maxBudgetUsd: costCap ? Math.max(0.01, costCap - sess.cost).toFixed(2) : undefined, disallow: mode === 2 ? READONLY_TOOLS : undefined }).then(finish); } else if (ENGINES[engine] && ENGINES[engine].kind === "cli") { // gemini / codex / opencode / aider const eng = ENGINES[engine]; const mdl = sess.model && sess.model !== engine ? sess.model : undefined; // only pass a model the user actually chose @@ -5939,7 +5952,7 @@ function nexusTui(engine, cwd, nexusMd, autoResume, launch) { row(tightEdits, "surgical edits — change only what differs, never rewrite whole lines"), row(cacheOn, "exact-repeat cache — free re-answers for unchanged read-only turns", impact.cachedHits ? gray(" " + impact.cachedHits + " hit" + (impact.cachedHits === 1 ? "" : "s") + " · $" + impact.cachedSaved.toFixed(4) + " saved") : isClaude ? gray(" (first message of a session only)") : ""), row(cheapSide, "local tab titles + recaps — no extra Claude Code session per title/recap", impact.sideSkipped ? gray(" " + impact.sideSkipped + " call" + (impact.sideSkipped === 1 ? "" : "s") + " skipped") : ""), - ...(isClaude ? [row(on, "unused skills listed by name only — still available, long descriptions not resent", trimmed ? gray(" " + trimmed + " skills") : on ? gray(" (starts after your next message)") : ""), row(on, "shared cache prefix — per-machine context kept out of the system prompt"), row(on, "model-switch hold — /model waits for a repeat while it would discard a warm cache")] : []), + ...(isClaude ? [row(on, "unused skills listed by name only — still available, long descriptions not resent", trimmed ? gray(" " + trimmed + " skills") : on ? gray(" (starts after your next message)") : ""), row(on, "shared cache prefix — per-machine context kept out of the system prompt"), row(on, "model-switch hold — /model waits for a repeat while it would discard a warm cache"), row(on, "keep-warm — refreshes a 1-hour cache before it expires while you are away (up to 6h)", impact.keepWarm ? gray(" " + impact.keepWarm + " refresh" + (impact.keepWarm === 1 ? "" : "es") + " · " + money(impact.keepWarmCost)) : "")] : []), row(null, "context de-dup, re-read supersession, unchanged-file skip", tk(impact.squeezeTok)), row(null, "repeated / counting output lines + node-internal frames → exact summaries", tk(impact.repeatTok) || localOnly), row(null, "repeated read-only tool calls → pointer to the identical earlier result", tk(impact.memoTok) || localOnly), diff --git a/lib/nexus/cheap.js b/lib/nexus/cheap.js index 71af85f..8730a08 100644 --- a/lib/nexus/cheap.js +++ b/lib/nexus/cheap.js @@ -21,13 +21,34 @@ const PRESET_KEYS = ["cache", "tightEdits", "cheapSide", "lean", "minimizeCalls" // Moves per-machine context out of the system prompt so sessions in different // folders can share the cached prefix. Safe on --resume in either direction. // skillOverrides ride along per launch, so the user's own settings stay untouched. -function launchFlags(on, overrides) { +// `quiet` (keep-warm pings only) turns hooks off: hooks are not part of the +// cached prefix, and a ping is not work that a Stop or review hook should see. +function launchFlags(on, overrides, quiet) { if (!on) return []; - const flags = ["--exclude-dynamic-system-prompt-sections"]; - if (overrides) flags.push("--settings", JSON.stringify({ skillOverrides: overrides })); + const flags = ["--exclude-dynamic-system-prompt-sections"], settings = {}; + if (overrides) settings.skillOverrides = overrides; + if (quiet) settings.disableAllHooks = true; + if (Object.keys(settings).length) flags.push("--settings", JSON.stringify(settings)); return flags; } +// Keep-warm: on a 1-hour cache, coming back after the hour rewrites the whole +// context at the write rate (about 80x a read on Fable). A one-turn ping just +// before expiry reads it instead and restarts the hour. The ping runs on a +// throwaway fork that is never saved, so the conversation itself is unchanged. +const KEEP_WARM_LEAD_MS = 4 * 60 * 1000; // ping inside the last 4 minutes +const KEEP_WARM_CAP_MS = 6 * HOUR_MS; // stop after 6 hours away: a long absence costs more in pings than one rebuild +const KEEP_WARM_MIN_CTX = 20000; // small contexts are cheap to rebuild +const KEEP_WARM_PROMPT = "Nexus keep-alive check. Reply with only: ok"; +function keepWarmDue(o) { + if (!o || !o.cheap || o.engine !== "claude" || !o.sid || o.busy || !o.lastAt) return false; + if (!(o.ttl >= HOUR_MS) || (o.ctxTok || 0) < KEEP_WARM_MIN_CTX) return false; // on a 5-minute cache a rebuild costs less than the pings + const left = o.lastAt + o.ttl - o.now; + if (left <= 0 || left > KEEP_WARM_LEAD_MS) return false; // expired already, or not yet near expiry + return o.now - (o.lastHumanAt || o.lastAt) < KEEP_WARM_CAP_MS; +} +const keepWarmFlags = () => ["--fork-session", "--no-session-persistence", "--max-turns", "1"]; + // Every skill's long description is resent in every session, used or not. // "name-only" keeps the skill listed and invocable and drops just that text. const DAY_MS = 24 * HOUR_MS, USE_WINDOW_MS = 30 * DAY_MS; @@ -138,4 +159,4 @@ function switchHold(o) { return { hold: true, pending: { to: o.to, at: o.now }, cost: switchCost(o) }; } -module.exports = { PRESET_KEYS, HOLD_MS, skillOverrides, projectSkills, scanSkillUse, rememberListed, overridesFor, refreshUse, launchFlags, mainBucket, spendReport, switchCost, switchHold }; +module.exports = { PRESET_KEYS, HOLD_MS, KEEP_WARM_PROMPT, KEEP_WARM_CAP_MS, keepWarmDue, keepWarmFlags, skillOverrides, projectSkills, scanSkillUse, rememberListed, overridesFor, refreshUse, launchFlags, mainBucket, spendReport, switchCost, switchHold }; diff --git a/test/run.js b/test/run.js index 8efef6e..0cc5638 100644 --- a/test/run.js +++ b/test/run.js @@ -3730,6 +3730,17 @@ ok("shouldCheck: first launch runs; throttled within 4h; runs after", shouldChec eq("flag only when on", CH.launchFlags(true).concat(CH.launchFlags(false)), ["--exclude-dynamic-system-prompt-sections"]); eq("overrides ride on --settings", CH.launchFlags(true, { pdf: "name-only" }).slice(1), ["--settings", '{"skillOverrides":{"pdf":"name-only"}}']); eq("overrides ignored when off", CH.launchFlags(false, { pdf: "name-only" }), []); + eq("keep-warm ping turns hooks off alongside overrides", CH.launchFlags(true, { pdf: "name-only" }, true).slice(1), ["--settings", '{"skillOverrides":{"pdf":"name-only"},"disableAllHooks":true}']); + eq("keep-warm ping runs one turn on an unsaved fork", CH.keepWarmFlags(), ["--fork-session", "--no-session-persistence", "--max-turns", "1"]); + const H = 3600000, kw = { cheap: true, engine: "claude", sid: "s1", busy: false, lastAt: H, ttl: H, now: 2 * H - 120000, lastHumanAt: H, ctxTok: 80000 }; + const due = (o) => CH.keepWarmDue(Object.assign({}, kw, o)); + ok("keep-warm fires 2 min before a 1h cache expires", due({})); + ok("keep-warm waits until the last 4 minutes", !due({ now: 2 * H - 10 * 60000 })); + ok("keep-warm never revives an expired cache", !due({ now: 2 * H + 1 })); + ok("keep-warm skips the 5m cache (rebuild is cheaper than pings)", !due({ ttl: 300000, now: H + 300000 - 60000 })); + ok("keep-warm skips small contexts", !due({ ctxTok: 5000 })); + ok("keep-warm off when /cheap is off, busy, no session or another engine", !due({ cheap: false }) && !due({ busy: true }) && !due({ sid: "" }) && !due({ engine: "gemini" })); + ok("keep-warm stops 6h after the last message", due({ lastAt: 5 * H, now: 6 * H - 60000 }) && !due({ lastAt: 7 * H, now: 8 * H - 60000 })); eq("unused skills go name-only, used and kept stay on", CH.skillOverrides(["pdf", "docs", "ship", "claude-api"], ["anthropic-skills:docs"], ["ship"]), { pdf: "name-only" }); ok("no scan yet = no trim", CH.skillOverrides(["pdf"], undefined) === null); ok("no listing yet = no trim", CH.skillOverrides(undefined, []) === null);