@inetafrica/open-claudia 3.0.5 → 3.0.6

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v3.0.6 — cache-bust burn is now a one-line query
+
+- **Usage records carry a `coldStart` flag.** The restart→cache-bust burn (each bot restart re-bills the whole accumulated window as cache *writes* instead of ~13×-cheaper cache *reads*) was invisible to every token-count analysis — same token counts, different price class — and took a forensic reconstruction of the 22-day usage history to quantify (~8% of all spend, ~$12/day at its worst). Now the first usage record a process writes for each session is tagged `coldStart: true`: a cold start mid-conversation is the restart fingerprint, so the burn is one jq filter away instead of a modelling exercise. Records already carried `cacheReadTokens`/`cacheCreationTokens`; this adds the missing "was the cache necessarily cold?" dimension.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change (additive JSONL field); Docker image builds identically. `usageSessionColdStart` covered by new assertions in `test-usage-accounting.js`.
+
 ## v3.0.5 — the conflict handler owns the poll
 
 - **Hiccup heals no longer fight the 409 backoff.** During a 409 conflict streak the conflict handler pauses polling and retries on its own schedule — but a network hiccup (`ECONNRESET`) arriving mid-streak would schedule its own heal, which called `startPolling` straight back into the conflict and reset the streak clock. This was the live v2.15 burn mechanism: its own ghost long-poll after an ECONNRESET heal raised a 409, the old code exited on any 409, launchd respawned it (~1/hr, 208 lifetime startups), and every restart busted the prompt cache so the next turn re-billed the whole accumulated window uncached. Hiccup handling is now a no-op while a conflict streak is active — the conflict handler owns the poll lifecycle.

package/core/runner.js

@@ -183,6 +183,7 @@ function logTurnUsage(state, usage, costUsd, announce, opts = {}) {
     billedContextTokens: parts.context,
     costUsd: typeof costUsd === "number" ? costUsd : 0,
   };
+  if (typeof opts.coldStart === "boolean") record.coldStart = opts.coldStart;
   if (opts.rawUsage && opts.rawUsage !== usage) {
     const raw = usageParts(opts.rawUsage, backend);
     record.rawInputTokens = raw.input;
@@ -1425,6 +1426,18 @@ async function persistForegroundTranscript(result, runContext, state = currentSt
   );
 }
 
+// Sessions this PROCESS has already recorded usage for. The first record per
+// session since boot is a cold start: the prompt cache is necessarily cold, so
+// the whole accumulated window re-bills as cache writes (~13x the read rate).
+// Restart burn is therefore one query away: coldStart=true mid-conversation.
+const warmUsageSessions = new Set();
+function usageSessionColdStart(sessionId, warmSet = warmUsageSessions) {
+  if (!sessionId) return true;
+  if (warmSet.has(sessionId)) return false;
+  warmSet.add(sessionId);
+  return true;
+}
+
 async function persistForegroundUsage(result, runContext, state = currentState(), store = chatContext.getStore()) {
   if (!result.usage) return;
   const previousUsageBySession = structuredClone(state.usageBySession || {});
@@ -1468,6 +1481,7 @@ async function persistForegroundUsage(result, runContext, state = currentState()
         usageScope,
         liveContextTokens,
         rawUsage,
+        coldStart: usageSessionColdStart(usageSessionId),
         strict: true,
       },
     );
@@ -2056,6 +2070,7 @@ module.exports = {
   effectiveCompactThreshold,
   usageParts,
   peakContextTokens,
+  usageSessionColdStart,
   clampUsageDelta,
   normalizeCodexUsage,
   applyUsageToState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "description": "An always-on, provider-agnostic coding-agent harness for Claude Code and OpenAI Codex via chat",
   "main": "bot.js",
   "bin": {

package/test-provider-language.js

@@ -32,11 +32,11 @@ assert.doesNotMatch(setup, /Your Claude Code bot is connected|Description=Claude
 
 const pkg = JSON.parse(read("package.json"));
 assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
-// 3.0.5 approved by Sumeet 2026-07-12 ("no do it on the latest co0de and push
-// a new version" — 409-conflict/heal/wedge guards so a token fight never
-// restarts the bot and busts the prompt cache; walker stays on per his call
-// that v2's walker was fine and v3's is identical).
-assert.strictEqual(pkg.version, "3.0.5", "release version must remain unchanged without explicit approval");
+// 3.0.6 approved by Sumeet 2026-07-12 ("Yeh you can do that too" — coldStart
+// flag on usage records so restart cache-bust burn, measured at ~8% of all
+// spend from the 22-day history, is a one-line query instead of a forensic
+// reconstruction).
+assert.strictEqual(pkg.version, "3.0.6", "release version must remain unchanged without explicit approval");
 for (const keyword of ["claude", "codex", "coding-agent", "provider-agnostic"]) {
   assert.ok(pkg.keywords.includes(keyword), `package keyword missing: ${keyword}`);
 }

package/test-usage-accounting.js

@@ -10,6 +10,7 @@ const {
   applyUsageToState,
   shouldAutoCompact,
   peakContextTokens,
+  usageSessionColdStart,
 } = require("./core/runner");
 const stateApi = require("./core/state");
 const { normalizeUsageRecord, loadUsageHistory, USAGE_HISTORY_FILE } = require("./core/usage-log");
@@ -176,5 +177,17 @@ assert.strictEqual(peakContextTokens([
   { type: "usage", scope: "provider_call", usage: { input_tokens: 70, cached_input_tokens: 30, output_tokens: 5 } },
 ], "codex"), 70, "codex context counts input only, matching usageParts");
 
+// usageSessionColdStart: the first usage record per session since process boot
+// is a cold start (prompt cache empty — the restart-burn fingerprint); every
+// later record for that session in the same process is warm.
+{
+  const warm = new Set();
+  assert.strictEqual(usageSessionColdStart("sess-a", warm), true, "first record for a session is cold");
+  assert.strictEqual(usageSessionColdStart("sess-a", warm), false, "second record for the same session is warm");
+  assert.strictEqual(usageSessionColdStart("sess-b", warm), true, "a different session is cold on its first record");
+  assert.strictEqual(usageSessionColdStart(null, warm), true, "no session id → always treated cold");
+  assert.strictEqual(usageSessionColdStart(null, warm), true, "null never warms");
+}
+
 fs.rmSync(configDir, { recursive: true, force: true });
 console.log("usage accounting OK");