@a1hvdy/cc-openclaw 0.29.0 → 0.30.0

package/dist/src/lib/cache-parity-decide.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Content-addressed cache-parity decision (v0.30.0).
+ *
+ * Problem (diagnosed 2026-05-23 from the live sysprompt-cost telemetry):
+ * cc-openclaw's cache-parity registry is keyed by sessionKey. The cache HIT
+ * path strips the role:system messages so the Claude CLI subprocess reuses its
+ * already-cached `--append-system-prompt` block; a MISS inlines the full ~7K
+ * system prompt into the user message (uncached). On the live box, 70% of all
+ * cache misses were `session_unknown` — the FIRST turn of a session, where the
+ * registry has no entry yet. Telegram conversations are short (median 1 turn /
+ * session, 23 of 35 single-turn), so cold-start dominated: the hit rate stalled
+ * at ~75% vs the terminal CLI's ~95%. The dynamic-envelope churn we originally
+ * set out to fix was only ~7.5% of turns.
+ *
+ * Key observation: every Savvy session shares the *identical* system prefix
+ * (same SOUL/USER/AGENTS/TOOLS/MEMORY + harness ⇒ same sysHash). So a brand-new
+ * session whose sysHash was already seen for some *other* session is a
+ * known-good prefix — its `--append-system-prompt` will be injected at
+ * startSession from the registry entry the route patch writes this same turn,
+ * so it is SAFE to strip the redundant inline and ride the cached path on
+ * turn 1 instead of re-billing the full prompt.
+ *
+ * Safety: the "warm-hash hit" only applies when the session is NEW (not yet in
+ * the SessionManager) — that guarantees startSession runs and appends the
+ * prompt. An EXISTING session missing its registry entry (e.g. registry wiped
+ * mid-life) keeps the legacy inline path so the model never loses its system
+ * prompt. A `hash_mismatch` (entry exists, different hash = genuine mid-session
+ * churn) also stays on the inline path: the CLI's append still holds the OLD
+ * prompt, so the new one must be delivered in-band.
+ *
+ * Pure + side-effect-free so the decision is unit-testable independent of the
+ * EmbeddedServer route closure (matches the codebase's pure-helper pattern:
+ * isPersistedSessionFresh, shouldWriteThroughResumeId).
+ */
+export type CacheParityAction = 'hit' | 'warm-hash-hit' | 'miss';
+export interface CacheParityDecisionInput {
+    /** Registry entry for THIS sessionKey, if any. */
+    entry: {
+        hash: string;
+    } | undefined;
+    /** sha1 of the (stripped) system content for this turn. */
+    sysHash: string;
+    /** True if sysHash has been seen for ANY session this process (known-good prefix). */
+    knownHash: boolean;
+    /**
+     * True if the SessionManager has no live session for this key yet. A new
+     * session guarantees startSession runs and injects appendSystemPrompt from
+     * the registry, which is what makes stripping the inline safe.
+     */
+    sessionIsNew: boolean;
+}
+/**
+ * Decide how the route patch should treat the system prompt this turn.
+ *
+ *  - 'hit'           → registry entry matches this session: strip role:system,
+ *                      ride the already-cached append.
+ *  - 'warm-hash-hit' → new session + known-good prefix: write the registry
+ *                      entry (so startSession appends it), strip role:system,
+ *                      ride the cached path. Closes the cold-start gap.
+ *  - 'miss'          → inline the system prompt into the user message (the safe
+ *                      legacy path): first-ever prefix, genuine churn, or an
+ *                      existing session that lost its registry entry.
+ */
+export declare function decideCacheParityAction(input: CacheParityDecisionInput): CacheParityAction;

package/dist/src/lib/cache-parity-decide.js

@@ -0,0 +1,54 @@
+/**
+ * Content-addressed cache-parity decision (v0.30.0).
+ *
+ * Problem (diagnosed 2026-05-23 from the live sysprompt-cost telemetry):
+ * cc-openclaw's cache-parity registry is keyed by sessionKey. The cache HIT
+ * path strips the role:system messages so the Claude CLI subprocess reuses its
+ * already-cached `--append-system-prompt` block; a MISS inlines the full ~7K
+ * system prompt into the user message (uncached). On the live box, 70% of all
+ * cache misses were `session_unknown` — the FIRST turn of a session, where the
+ * registry has no entry yet. Telegram conversations are short (median 1 turn /
+ * session, 23 of 35 single-turn), so cold-start dominated: the hit rate stalled
+ * at ~75% vs the terminal CLI's ~95%. The dynamic-envelope churn we originally
+ * set out to fix was only ~7.5% of turns.
+ *
+ * Key observation: every Savvy session shares the *identical* system prefix
+ * (same SOUL/USER/AGENTS/TOOLS/MEMORY + harness ⇒ same sysHash). So a brand-new
+ * session whose sysHash was already seen for some *other* session is a
+ * known-good prefix — its `--append-system-prompt` will be injected at
+ * startSession from the registry entry the route patch writes this same turn,
+ * so it is SAFE to strip the redundant inline and ride the cached path on
+ * turn 1 instead of re-billing the full prompt.
+ *
+ * Safety: the "warm-hash hit" only applies when the session is NEW (not yet in
+ * the SessionManager) — that guarantees startSession runs and appends the
+ * prompt. An EXISTING session missing its registry entry (e.g. registry wiped
+ * mid-life) keeps the legacy inline path so the model never loses its system
+ * prompt. A `hash_mismatch` (entry exists, different hash = genuine mid-session
+ * churn) also stays on the inline path: the CLI's append still holds the OLD
+ * prompt, so the new one must be delivered in-band.
+ *
+ * Pure + side-effect-free so the decision is unit-testable independent of the
+ * EmbeddedServer route closure (matches the codebase's pure-helper pattern:
+ * isPersistedSessionFresh, shouldWriteThroughResumeId).
+ */
+/**
+ * Decide how the route patch should treat the system prompt this turn.
+ *
+ *  - 'hit'           → registry entry matches this session: strip role:system,
+ *                      ride the already-cached append.
+ *  - 'warm-hash-hit' → new session + known-good prefix: write the registry
+ *                      entry (so startSession appends it), strip role:system,
+ *                      ride the cached path. Closes the cold-start gap.
+ *  - 'miss'          → inline the system prompt into the user message (the safe
+ *                      legacy path): first-ever prefix, genuine churn, or an
+ *                      existing session that lost its registry entry.
+ */
+export function decideCacheParityAction(input) {
+    const { entry, sysHash, knownHash, sessionIsNew } = input;
+    if (entry && entry.hash === sysHash)
+        return 'hit';
+    if (!entry && knownHash && sessionIsNew)
+        return 'warm-hash-hit';
+    return 'miss';
+}

package/dist/src/lib/index.d.ts

@@ -0,0 +1,7 @@
+export * from './register-guard.js';
+export { registerOnce } from './register-guard.js';
+export { stripSysprompt, isStripEnabled, type StripOptions, type StripResult } from './sysprompt-strip.js';
+export { isCacheParityEnabled, hashPrompt, recordAttachment, readRegistry, REGISTRY_PATH, type RegistryEntry, } from './cache-parity.js';
+export { selectEngine, isCcOpenclawEnabled, captureSessionRoute, ACTIVE_FLAG_ENV, ROUTE_FLAG_ENV, type Engine, type SessionRoute, } from './config-service.js';
+export { isTestMode, TEST_MODE_ENV, _setTestModeForTests } from './test-mode.js';
+export { getAggressiveStripEnabled, getCacheParityEnabled, getLogLevel, isLogLevelDebug, } from './config.js';

package/dist/src/lib/index.js

@@ -0,0 +1,10 @@
+export * from './register-guard.js';
+export { registerOnce } from './register-guard.js';
+export { stripSysprompt, isStripEnabled } from './sysprompt-strip.js';
+export { isCacheParityEnabled, hashPrompt, recordAttachment, readRegistry, REGISTRY_PATH, } from './cache-parity.js';
+// Engine routing — originally `./route-flag.js`; collapsed into
+// `./config-service.js` at Cluster A step 8. Same API, same semantics,
+// single source of truth.
+export { selectEngine, isCcOpenclawEnabled, captureSessionRoute, ACTIVE_FLAG_ENV, ROUTE_FLAG_ENV, } from './config-service.js';
+export { isTestMode, TEST_MODE_ENV, _setTestModeForTests } from './test-mode.js';
+export { getAggressiveStripEnabled, getCacheParityEnabled, getLogLevel, isLogLevelDebug, } from './config.js';

package/dist/src/observability/perf-telemetry.d.ts

@@ -27,7 +27,7 @@
  * break the single `jq` pipeline. The `event` field makes filtering trivial.
  */
 type PerfEventName = 'cache_check' | 'first_byte' | 'turn_end';
-type CacheCheckCause = 'hit' | 'registry_empty' | 'hash_mismatch' | 'session_unknown' | 'disabled';
+type CacheCheckCause = 'hit' | 'warm_hash' | 'registry_empty' | 'hash_mismatch' | 'session_unknown' | 'disabled';
 interface PerfEventBase {
     event: PerfEventName;
     sessionKey?: string;

package/dist/src/session-bootstrap/cwd-patch.js

@@ -37,6 +37,7 @@ import { defaultRegisterGuard } from '../lib/register-guard.js';
 import { isTestMode } from '../lib/test-mode.js';
 import { writePerfEvent } from '../observability/perf-telemetry.js';
 import { collapseSkillList } from '../lib/perf/skill-list-collapse.js';
+import { decideCacheParityAction } from '../lib/cache-parity-decide.js';
 import { isCacheParityTrackB, isTokenTelemetryEnabled, isSyspromptDumpEnabled, getMaxConcurrentSessions, getSessionTtlMinutes, ensureUxBridgeAllSessionsDefault, } from '../lib/config.js';
 import { VENDOR_FILES } from '../lib/vendor-paths.js';
 import { OpenClawConfigSchema, findMainAgent, getAgentPrimaryModel, getDefaultsPrimaryModel, isClaudeRoutedModel, } from '../types/upstream.js';
@@ -99,6 +100,7 @@ const METRICS = {
     systemPromptInlined: 0,
     uxMetaSeeded: 0,
     cacheParityHits: 0,
+    cacheParityWarmHashHits: 0,
     cacheParityMisses: 0,
     cacheParityRegistryWrites: 0,
     cacheParityAppendInjections: 0,
@@ -143,6 +145,24 @@ function _setSystemInlineCache(key, val) {
     }
     _systemInlineCache.set(key, val);
 }
+// ── Known sysprompt-hash set (v0.30.0 — content-addressed cache parity) ──────
+// Cross-session record of every sysHash written to the cache-parity registry
+// this process. Lets a brand-new session recognise the shared Savvy system
+// prefix and ride the cached append path on turn 1 instead of inlining the full
+// ~7K prompt — the dominant cold-start miss (see lib/cache-parity-decide.ts).
+// Bounded FIFO: distinct prefixes are few (one per build), 64 is ample headroom.
+const _knownSysHashes = new Set();
+const KNOWN_SYS_HASH_MAX = 64;
+function _rememberSysHash(hash) {
+    if (_knownSysHashes.has(hash))
+        return;
+    if (_knownSysHashes.size >= KNOWN_SYS_HASH_MAX) {
+        const oldest = _knownSysHashes.values().next().value;
+        if (oldest !== undefined)
+            _knownSysHashes.delete(oldest);
+    }
+    _knownSysHashes.add(hash);
+}
 // ── Tool dump hash guard (v0.6.0 — per-session-key cache + fast-skip) ──
 // Pre-v0.6.0: a single global `_lastToolDumpHash` thrashed when multiple
 // sessions had different tool sets. JSON.stringify + SHA1 ran on EVERY
@@ -655,11 +675,30 @@ function applyRoutePatch(EmbeddedServer) {
                         try {
                             const reg = _readCacheParityRegistry();
                             const entry = reg[sessionKey];
-                            if (entry && entry.hash === sysHash) {
+                            // sessionIsNew: no live session in the manager ⇒ startSession will
+                            // run on this request and inject appendSystemPrompt from the
+                            // registry entry we write below. That guarantee is what makes the
+                            // warm-hash strip safe (see lib/cache-parity-decide.ts). Default
+                            // to false on any access failure — conservative: an unproven
+                            // append guarantee falls back to the safe inline path.
+                            let sessionIsNew = false;
+                            try {
+                                const mgr = this.manager;
+                                sessionIsNew = !(mgr?.sessions?.has?.('openai-' + sessionKey) ?? false);
+                            }
+                            catch { /* keep sessionIsNew=false (inline fallback) */ }
+                            const action = decideCacheParityAction({
+                                entry: entry ? { hash: entry.hash } : undefined,
+                                sysHash,
+                                knownHash: _knownSysHashes.has(sysHash),
+                                sessionIsNew,
+                            });
+                            if (action === 'hit') {
                                 body.messages = messages.filter(m => m?.role !== 'system');
                                 METRICS.cacheParityHits++;
                                 METRICS.systemPromptInlined++;
                                 cacheParityHandled = true;
+                                _rememberSysHash(sysHash);
                                 writePerfEvent({
                                     event: 'cache_check',
                                     sessionKey,
@@ -668,8 +707,29 @@ function applyRoutePatch(EmbeddedServer) {
                                     sysHash,
                                 });
                             }
+                            else if (action === 'warm-hash-hit') {
+                                // Cold-start win: new session + known-good Savvy prefix. Write
+                                // the entry so startSession appends it, strip the redundant
+                                // inline, ride the cached path on turn 1.
+                                _writeCacheParityEntry(sessionKey, sysHash, sysContent);
+                                body.messages = messages.filter(m => m?.role !== 'system');
+                                METRICS.cacheParityWarmHashHits++;
+                                METRICS.cacheParityRegistryWrites++;
+                                METRICS.systemPromptInlined++;
+                                cacheParityHandled = true;
+                                _rememberSysHash(sysHash);
+                                logger.info(`${TAG} cache-parity warm-hash hit: session=${sessionKey} hash=${sysHash} sysLen=${sysContent.length} (cold-start dedup; startSession will append)`);
+                                writePerfEvent({
+                                    event: 'cache_check',
+                                    sessionKey,
+                                    outcome: 'hit',
+                                    cause: 'warm_hash',
+                                    sysHash,
+                                });
+                            }
                             else {
                                 _writeCacheParityEntry(sessionKey, sysHash, sysContent);
+                                _rememberSysHash(sysHash);
                                 METRICS.cacheParityMisses++;
                                 METRICS.cacheParityRegistryWrites++;
                                 logger.info(`${TAG} cache-parity miss: session=${sessionKey} oldHash=${entry?.hash || 'none'} newHash=${sysHash} sysLen=${sysContent.length} (registry updated; next session start will append)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a1hvdy/cc-openclaw",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "A1xAI's Anthropic CLI bridge plugin for OpenClaw",
   "author": "@a1cy",
   "license": "MIT",