@a1hvdy/cc-openclaw 0.3.2

package/dist/src/lib/drift-detector.js

@@ -0,0 +1,192 @@
+// phase: 4 | pillar: 2 | agent: P2.B
+/**
+ * drift-detector — cross-laptop version mismatch detection.
+ *
+ * On register() and every 5 minutes (default), captures:
+ *   { laptopId, ccOpenclawBuildHash, openclawBinaryVersion, claudeCodeVersion, ts }
+ *
+ * Writes to ~/.openclaw/state/cc-openclaw-version-state.json (one slot per
+ * laptopId) per handoff system slot rule. Compares own slot vs other laptop
+ * slots; on mismatch fires Telegram alert + drift.jsonl row with 1h dedup.
+ *
+ * Configurable via:
+ *   OPENCLAW_CC_OPENCLAW_DRIFT_ALERTS=0          — disable Telegram noise
+ *   OPENCLAW_CC_OPENCLAW_DRIFT_DEDUPE_WINDOW_MS  — dedup window (default 3600000)
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir, hostname } from 'node:os';
+import { createHash } from 'node:crypto';
+import { formatError, ERROR_CODES } from './error-formatter.js';
+import { renderError } from '../channels/telegram/error-renderer.js';
+// ─── Config ───────────────────────────────────────────────────────────────────
+const STATE_PATH = join(homedir(), '.openclaw', 'state', 'cc-openclaw-version-state.json');
+const POLL_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+function isDriftAlertsEnabled() {
+    return process.env.OPENCLAW_CC_OPENCLAW_DRIFT_ALERTS !== '0';
+}
+function getDedupWindowMs() {
+    const v = process.env.OPENCLAW_CC_OPENCLAW_DRIFT_DEDUPE_WINDOW_MS;
+    const n = v !== undefined ? parseInt(v, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : 3_600_000;
+}
+// ─── Version capture helpers ─────────────────────────────────────────────────
+function safeExec(cmd, fallback) {
+    try {
+        return execSync(cmd, { timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim();
+    }
+    catch {
+        return fallback;
+    }
+}
+function resolveLaptopId() {
+    // Prefer env override for test isolation, then hostname
+    return process.env.OPENCLAW_LAPTOP_ID || hostname();
+}
+function resolveBuildHash() {
+    // Hash of own package.json version + the dist/src/index.js mtime for change detection
+    try {
+        const pkgPath = join(dirname(new URL(import.meta.url).pathname), '../../package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const version = pkg.version ?? 'unknown';
+        return createHash('sha1').update(version).digest('hex').slice(0, 12);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function resolveOpenclawBinaryVersion() {
+    return safeExec('openclaw --version 2>/dev/null || openclaw version 2>/dev/null', 'unknown');
+}
+function resolveClaudeCodeVersion() {
+    return safeExec('claude --version 2>/dev/null', 'unknown');
+}
+export function captureVersionSlot() {
+    return {
+        laptopId: resolveLaptopId(),
+        ccOpenclawBuildHash: resolveBuildHash(),
+        openclawBinaryVersion: resolveOpenclawBinaryVersion(),
+        claudeCodeVersion: resolveClaudeCodeVersion(),
+        ts: new Date().toISOString(),
+    };
+}
+// ─── State file I/O ───────────────────────────────────────────────────────────
+function readStateFile() {
+    try {
+        if (!existsSync(STATE_PATH))
+            return {};
+        const raw = readFileSync(STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function writeStateFile(state) {
+    try {
+        const dir = dirname(STATE_PATH);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(STATE_PATH, JSON.stringify(state, null, 2) + '\n');
+    }
+    catch (err) {
+        process.stderr.write(`[cc-openclaw/drift-detector] state write failed: ${err.message}\n`);
+    }
+}
+// ─── Drift comparison ─────────────────────────────────────────────────────────
+const COMPARED_FIELDS = [
+    'ccOpenclawBuildHash',
+    'openclawBinaryVersion',
+    'claudeCodeVersion',
+];
+function detectDrift(own, state) {
+    const conflictingSlots = [];
+    for (const [laptopId, slot] of Object.entries(state)) {
+        if (laptopId === own.laptopId)
+            continue;
+        const mismatchedFields = COMPARED_FIELDS.filter((f) => slot[f] !== own[f]);
+        if (mismatchedFields.length > 0) {
+            conflictingSlots.push({ laptopId, slot, fields: mismatchedFields });
+        }
+    }
+    return {
+        detected: conflictingSlots.length > 0,
+        ownSlot: own,
+        conflictingSlots,
+    };
+}
+// ─── Alert dedup (module-level) ───────────────────────────────────────────────
+let _lastDriftAlertAt = 0;
+function isDriftAlertDue() {
+    return Date.now() - _lastDriftAlertAt > getDedupWindowMs();
+}
+function markDriftAlerted() {
+    _lastDriftAlertAt = Date.now();
+}
+/** Test-only reset. */
+export function _resetDriftAlertForTests() {
+    _lastDriftAlertAt = 0;
+}
+// ─── Core check function ──────────────────────────────────────────────────────
+/**
+ * Capture own slot, update state file, compare with other laptops.
+ * Fires Telegram + jsonl on mismatch (with 1h dedup).
+ *
+ * Returns the DriftReport so callers can react programmatically.
+ */
+export async function checkDrift() {
+    const own = captureVersionSlot();
+    const state = readStateFile();
+    // Update own slot
+    state[own.laptopId] = own;
+    writeStateFile(state);
+    const report = detectDrift(own, state);
+    if (report.detected && isDriftAlertsEnabled() && isDriftAlertDue()) {
+        markDriftAlerted();
+        const firstConflict = report.conflictingSlots[0];
+        const details = {
+            otherLaptop: firstConflict.laptopId,
+            mismatchedFields: firstConflict.fields.join(', '),
+            ownBuildHash: own.ccOpenclawBuildHash,
+            otherBuildHash: firstConflict.slot.ccOpenclawBuildHash,
+            ownOpenclawVersion: own.openclawBinaryVersion,
+            otherOpenclawVersion: firstConflict.slot.openclawBinaryVersion,
+        };
+        const formatted = formatError(new Error(`Version drift detected vs ${firstConflict.laptopId}: ` +
+            firstConflict.fields.map((f) => `${f}=${firstConflict.slot[f]}`).join(', ')), {
+            code: ERROR_CODES.DRIFT_DETECTED,
+            laptopId: own.laptopId,
+            details,
+        });
+        await renderError(formatted, { writeJsonl: true });
+    }
+    return report;
+}
+// ─── Polling lifecycle ────────────────────────────────────────────────────────
+let _pollTimer = null;
+export function startDriftPolling() {
+    if (_pollTimer !== null)
+        return; // already running
+    _pollTimer = setInterval(() => {
+        checkDrift().catch((err) => {
+            process.stderr.write(`[cc-openclaw/drift-detector] poll error: ${err.message}\n`);
+        });
+    }, POLL_INTERVAL_MS);
+    // Unref so the timer doesn't keep the process alive in test/short-lived contexts
+    if (_pollTimer.unref)
+        _pollTimer.unref();
+}
+export function stopDriftPolling() {
+    if (_pollTimer !== null) {
+        clearInterval(_pollTimer);
+        _pollTimer = null;
+    }
+}
+/** Test-only: check if polling is active. */
+export function _isDriftPollingActive() {
+    return _pollTimer !== null;
+}
+//# sourceMappingURL=drift-detector.js.map

package/dist/src/lib/drift-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-detector.js","sourceRoot":"","sources":["../../../src/lib/drift-detector.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/error-formatter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * error-formatter — pure ({error, context}) => {jsonlRow, telegramText}
+ *
+ * Structured error taxonomy for cc-openclaw. Every catchable error site
+ * should pass through here so errors are never "Error: undefined" in
+ * Telegram or jsonl outputs.
+ *
+ * Error code taxonomy:
+ *   CC_OPENCLAW_TOOL_FAILURE        — tool invocation failed
+ *   CC_OPENCLAW_BUDGET_EXCEEDED     — quota/budget limit hit
+ *   CC_OPENCLAW_GATEWAY_CRASH       — PM2 process exited unexpectedly
+ *   CC_OPENCLAW_DRIFT_DETECTED      — cross-laptop version mismatch
+ *   CC_OPENCLAW_HEALTH_PROBE_FAILED — /health endpoint unreachable
+ *   CC_OPENCLAW_RECOVERY_FAILED     — auto-recovery did not succeed
+ *   CC_OPENCLAW_RECOVERY_OK         — auto-recovery succeeded (info)
+ *   CC_OPENCLAW_SESSION_ERROR       — session-level error
+ *   CC_OPENCLAW_PARSE_ERROR         — stream parsing error
+ *   CC_OPENCLAW_CONFIG_ERROR        — configuration/env error
+ *   CC_OPENCLAW_NETWORK_ERROR       — upstream HTTP/network failure
+ *   CC_OPENCLAW_TIMEOUT             — operation exceeded time limit
+ *   CC_OPENCLAW_AUTH_ERROR          — authentication/API key failure
+ *   CC_OPENCLAW_UNKNOWN             — unclassified error
+ */
+export declare const ERROR_CODES: {
+    readonly TOOL_FAILURE: "CC_OPENCLAW_TOOL_FAILURE";
+    readonly BUDGET_EXCEEDED: "CC_OPENCLAW_BUDGET_EXCEEDED";
+    readonly GATEWAY_CRASH: "CC_OPENCLAW_GATEWAY_CRASH";
+    readonly DRIFT_DETECTED: "CC_OPENCLAW_DRIFT_DETECTED";
+    readonly HEALTH_PROBE_FAILED: "CC_OPENCLAW_HEALTH_PROBE_FAILED";
+    readonly RECOVERY_FAILED: "CC_OPENCLAW_RECOVERY_FAILED";
+    readonly RECOVERY_OK: "CC_OPENCLAW_RECOVERY_OK";
+    readonly SESSION_ERROR: "CC_OPENCLAW_SESSION_ERROR";
+    readonly PARSE_ERROR: "CC_OPENCLAW_PARSE_ERROR";
+    readonly CONFIG_ERROR: "CC_OPENCLAW_CONFIG_ERROR";
+    readonly NETWORK_ERROR: "CC_OPENCLAW_NETWORK_ERROR";
+    readonly TIMEOUT: "CC_OPENCLAW_TIMEOUT";
+    readonly AUTH_ERROR: "CC_OPENCLAW_AUTH_ERROR";
+    readonly UNKNOWN: "CC_OPENCLAW_UNKNOWN";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+export type Severity = 'critical' | 'error' | 'warning' | 'info';
+export interface ErrorContext {
+    code: ErrorCode;
+    sessionId?: string;
+    laptopId?: string;
+    /** Additional structured key-value details */
+    details?: Record<string, unknown>;
+}
+export interface FormattedError {
+    /** NDJSON-ready row */
+    jsonlRow: ErrorJsonlRow;
+    /** Telegram message text (MarkdownV2-safe) */
+    telegramText: string;
+}
+export interface ErrorJsonlRow {
+    ts: string;
+    code: ErrorCode;
+    severity: Severity;
+    message: string;
+    sessionId?: string;
+    laptopId?: string;
+    stack?: string;
+    details?: Record<string, unknown>;
+}
+/** Extract a usable message from unknown thrown values. */
+export declare function extractMessage(error: unknown): string;
+/** Escape characters special to Telegram MarkdownV2. */
+export declare function escapeMdV2(text: string): string;
+/**
+ * Pure formatter — no side effects, fully unit-testable.
+ *
+ * @param error   The thrown value (Error instance, string, or unknown)
+ * @param context Structured context including mandatory error code
+ */
+export declare function formatError(error: unknown, context: ErrorContext): FormattedError;
+/** Shorthand for the common "unknown catch block" pattern. */
+export declare function formatUnknownError(error: unknown, sessionId?: string): FormattedError;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/src/lib/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../../src/lib/error-formatter.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;CAed,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAqBjE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,uBAAuB;IACvB,QAAQ,EAAE,aAAa,CAAC;IACxB,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAID,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUrD;AAWD,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAWD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,GAAG,cAAc,CA6CjF;AAID,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CAKrF"}

package/dist/src/lib/error-formatter.js

@@ -0,0 +1,149 @@
+// phase: 4 | pillar: 2 | agent: P2.B
+/**
+ * error-formatter — pure ({error, context}) => {jsonlRow, telegramText}
+ *
+ * Structured error taxonomy for cc-openclaw. Every catchable error site
+ * should pass through here so errors are never "Error: undefined" in
+ * Telegram or jsonl outputs.
+ *
+ * Error code taxonomy:
+ *   CC_OPENCLAW_TOOL_FAILURE        — tool invocation failed
+ *   CC_OPENCLAW_BUDGET_EXCEEDED     — quota/budget limit hit
+ *   CC_OPENCLAW_GATEWAY_CRASH       — PM2 process exited unexpectedly
+ *   CC_OPENCLAW_DRIFT_DETECTED      — cross-laptop version mismatch
+ *   CC_OPENCLAW_HEALTH_PROBE_FAILED — /health endpoint unreachable
+ *   CC_OPENCLAW_RECOVERY_FAILED     — auto-recovery did not succeed
+ *   CC_OPENCLAW_RECOVERY_OK         — auto-recovery succeeded (info)
+ *   CC_OPENCLAW_SESSION_ERROR       — session-level error
+ *   CC_OPENCLAW_PARSE_ERROR         — stream parsing error
+ *   CC_OPENCLAW_CONFIG_ERROR        — configuration/env error
+ *   CC_OPENCLAW_NETWORK_ERROR       — upstream HTTP/network failure
+ *   CC_OPENCLAW_TIMEOUT             — operation exceeded time limit
+ *   CC_OPENCLAW_AUTH_ERROR          — authentication/API key failure
+ *   CC_OPENCLAW_UNKNOWN             — unclassified error
+ */
+// ─── Error code taxonomy ─────────────────────────────────────────────────────
+export const ERROR_CODES = {
+    TOOL_FAILURE: 'CC_OPENCLAW_TOOL_FAILURE',
+    BUDGET_EXCEEDED: 'CC_OPENCLAW_BUDGET_EXCEEDED',
+    GATEWAY_CRASH: 'CC_OPENCLAW_GATEWAY_CRASH',
+    DRIFT_DETECTED: 'CC_OPENCLAW_DRIFT_DETECTED',
+    HEALTH_PROBE_FAILED: 'CC_OPENCLAW_HEALTH_PROBE_FAILED',
+    RECOVERY_FAILED: 'CC_OPENCLAW_RECOVERY_FAILED',
+    RECOVERY_OK: 'CC_OPENCLAW_RECOVERY_OK',
+    SESSION_ERROR: 'CC_OPENCLAW_SESSION_ERROR',
+    PARSE_ERROR: 'CC_OPENCLAW_PARSE_ERROR',
+    CONFIG_ERROR: 'CC_OPENCLAW_CONFIG_ERROR',
+    NETWORK_ERROR: 'CC_OPENCLAW_NETWORK_ERROR',
+    TIMEOUT: 'CC_OPENCLAW_TIMEOUT',
+    AUTH_ERROR: 'CC_OPENCLAW_AUTH_ERROR',
+    UNKNOWN: 'CC_OPENCLAW_UNKNOWN',
+};
+const SEVERITY_BY_CODE = {
+    [ERROR_CODES.TOOL_FAILURE]: 'error',
+    [ERROR_CODES.BUDGET_EXCEEDED]: 'warning',
+    [ERROR_CODES.GATEWAY_CRASH]: 'critical',
+    [ERROR_CODES.DRIFT_DETECTED]: 'warning',
+    [ERROR_CODES.HEALTH_PROBE_FAILED]: 'error',
+    [ERROR_CODES.RECOVERY_FAILED]: 'critical',
+    [ERROR_CODES.RECOVERY_OK]: 'info',
+    [ERROR_CODES.SESSION_ERROR]: 'error',
+    [ERROR_CODES.PARSE_ERROR]: 'error',
+    [ERROR_CODES.CONFIG_ERROR]: 'critical',
+    [ERROR_CODES.NETWORK_ERROR]: 'error',
+    [ERROR_CODES.TIMEOUT]: 'warning',
+    [ERROR_CODES.AUTH_ERROR]: 'critical',
+    [ERROR_CODES.UNKNOWN]: 'error',
+};
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/** Extract a usable message from unknown thrown values. */
+export function extractMessage(error) {
+    if (error === null || error === undefined)
+        return '(no error message)';
+    if (typeof error === 'string')
+        return error.trim() || '(empty string error)';
+    if (error instanceof Error)
+        return error.message || error.name || '(empty Error message)';
+    try {
+        const s = JSON.stringify(error);
+        return s.length > 200 ? s.slice(0, 200) + '...' : s;
+    }
+    catch {
+        return String(error);
+    }
+}
+/** Extract stack trace when available. */
+function extractStack(error) {
+    if (error instanceof Error && error.stack) {
+        // Trim to 3 lines to keep jsonl rows compact
+        return error.stack.split('\n').slice(0, 4).join('\n');
+    }
+    return undefined;
+}
+/** Escape characters special to Telegram MarkdownV2. */
+export function escapeMdV2(text) {
+    // Per Telegram docs, these must be escaped: _ * [ ] ( ) ~ ` > # + - = | { } . !
+    return text.replace(/[_*[\]()~`>#+=|{}.!\\-]/g, (c) => `\\${c}`);
+}
+const SEVERITY_EMOJI = {
+    critical: '🚨',
+    error: '❌',
+    warning: '⚠️',
+    info: '✅',
+};
+// ─── Core formatter ───────────────────────────────────────────────────────────
+/**
+ * Pure formatter — no side effects, fully unit-testable.
+ *
+ * @param error   The thrown value (Error instance, string, or unknown)
+ * @param context Structured context including mandatory error code
+ */
+export function formatError(error, context) {
+    const message = extractMessage(error);
+    const stack = extractStack(error);
+    const severity = SEVERITY_BY_CODE[context.code] ?? 'error';
+    const ts = new Date().toISOString();
+    const jsonlRow = {
+        ts,
+        code: context.code,
+        severity,
+        message,
+        ...(context.sessionId !== undefined ? { sessionId: context.sessionId } : {}),
+        ...(context.laptopId !== undefined ? { laptopId: context.laptopId } : {}),
+        ...(stack !== undefined ? { stack } : {}),
+        ...(context.details !== undefined ? { details: context.details } : {}),
+    };
+    const emoji = SEVERITY_EMOJI[severity];
+    const safeCode = escapeMdV2(context.code);
+    const safeMsg = escapeMdV2(message.length > 300 ? message.slice(0, 300) + '...' : message);
+    const safeTs = escapeMdV2(ts.slice(0, 19).replace('T', ' '));
+    const lines = [
+        `${emoji} *${safeCode}*`,
+        `\`${safeMsg}\``,
+        `_${safeTs}_`,
+    ];
+    if (context.sessionId) {
+        lines.push(`session: \`${escapeMdV2(context.sessionId)}\``);
+    }
+    if (context.laptopId) {
+        lines.push(`laptop: \`${escapeMdV2(context.laptopId)}\``);
+    }
+    if (context.details && Object.keys(context.details).length > 0) {
+        const detailParts = Object.entries(context.details)
+            .slice(0, 5)
+            .map(([k, v]) => `${escapeMdV2(k)}: ${escapeMdV2(String(v))}`)
+            .join(', ');
+        lines.push(`_${detailParts}_`);
+    }
+    const telegramText = lines.join('\n');
+    return { jsonlRow, telegramText };
+}
+// ─── Convenience factory  ─────────────────────────────────────────────────────
+/** Shorthand for the common "unknown catch block" pattern. */
+export function formatUnknownError(error, sessionId) {
+    return formatError(error, {
+        code: ERROR_CODES.UNKNOWN,
+        sessionId,
+    });
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/src/lib/error-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.js","sourceRoot":"","sources":["../../../src/lib/error-formatter.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/heartbeat-workaround.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Heartbeat model workaround — SDK-call-layer override.
+ *
+ * Tracks OpenClaw issues #9556, #13009, #14279: heartbeat-triggered runs
+ * ignore the heartbeat.model field and use the session's primary model
+ * (typically Opus). This wastes tokens and adds latency on what should be
+ * a cheap Haiku ping.
+ *
+ * applyHeartbeatWorkaround() inspects an SDK request payload, detects
+ * heartbeat-shaped requests via heuristics (low input tokens + heartbeat
+ * sentinel in messages), and forces the model field to the heartbeat.model
+ * value (or HEARTBEAT_FALLBACK_MODEL when missing).
+ *
+ * Disable via CC_OPENCLAW_DISABLE_HEARTBEAT_WORKAROUND=1 — set this when
+ * upstream OpenClaw ships a native fix.
+ */
+export declare const HEARTBEAT_FALLBACK_MODEL = "claude-haiku-4-5";
+/** Sentinel strings observed in upstream OpenClaw heartbeat payloads. */
+export declare const HEARTBEAT_SENTINELS: readonly ["__heartbeat__", "heartbeat:ping", "__keepalive__"];
+export interface SdkRequestPayload {
+    model: string;
+    messages?: Array<{
+        role: string;
+        content: string | unknown;
+    }>;
+    metadata?: Record<string, unknown>;
+    /** Some payloads carry the intended heartbeat model in metadata or top-level */
+    heartbeat?: {
+        model?: string;
+    };
+}
+/**
+ * Heuristic: a request is heartbeat-shaped if:
+ *   - metadata.heartbeat or top-level heartbeat field is set, OR
+ *   - any message content contains a heartbeat sentinel, OR
+ *   - metadata flag `is_heartbeat: true`
+ */
+export declare function isHeartbeatRequest(req: SdkRequestPayload): boolean;
+/**
+ * Apply the workaround: if the request is heartbeat-shaped and the workaround
+ * is not disabled, override the model to the heartbeat target. Returns a NEW
+ * payload object (does not mutate input).
+ */
+export declare function applyHeartbeatWorkaround(req: SdkRequestPayload): SdkRequestPayload;
+//# sourceMappingURL=heartbeat-workaround.d.ts.map

package/dist/src/lib/heartbeat-workaround.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-workaround.d.ts","sourceRoot":"","sources":["../../../src/lib/heartbeat-workaround.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,+DAAgE,CAAC;AAEjG,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,gFAAgF;IAChF,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAclE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,iBAAiB,GAAG,iBAAiB,CAOlF"}

package/dist/src/lib/heartbeat-workaround.js

@@ -0,0 +1,61 @@
+/**
+ * Heartbeat model workaround — SDK-call-layer override.
+ *
+ * Tracks OpenClaw issues #9556, #13009, #14279: heartbeat-triggered runs
+ * ignore the heartbeat.model field and use the session's primary model
+ * (typically Opus). This wastes tokens and adds latency on what should be
+ * a cheap Haiku ping.
+ *
+ * applyHeartbeatWorkaround() inspects an SDK request payload, detects
+ * heartbeat-shaped requests via heuristics (low input tokens + heartbeat
+ * sentinel in messages), and forces the model field to the heartbeat.model
+ * value (or HEARTBEAT_FALLBACK_MODEL when missing).
+ *
+ * Disable via CC_OPENCLAW_DISABLE_HEARTBEAT_WORKAROUND=1 — set this when
+ * upstream OpenClaw ships a native fix.
+ */
+import { isHeartbeatWorkaroundDisabled } from './config.js';
+export const HEARTBEAT_FALLBACK_MODEL = 'claude-haiku-4-5';
+/** Sentinel strings observed in upstream OpenClaw heartbeat payloads. */
+export const HEARTBEAT_SENTINELS = ['__heartbeat__', 'heartbeat:ping', '__keepalive__'];
+/**
+ * Heuristic: a request is heartbeat-shaped if:
+ *   - metadata.heartbeat or top-level heartbeat field is set, OR
+ *   - any message content contains a heartbeat sentinel, OR
+ *   - metadata flag `is_heartbeat: true`
+ */
+export function isHeartbeatRequest(req) {
+    if (req.heartbeat?.model)
+        return true;
+    if (req.metadata?.heartbeat)
+        return true;
+    if (req.metadata?.is_heartbeat === true)
+        return true;
+    if (Array.isArray(req.messages)) {
+        for (const msg of req.messages) {
+            if (typeof msg.content === 'string') {
+                for (const sentinel of HEARTBEAT_SENTINELS) {
+                    if (msg.content.includes(sentinel))
+                        return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Apply the workaround: if the request is heartbeat-shaped and the workaround
+ * is not disabled, override the model to the heartbeat target. Returns a NEW
+ * payload object (does not mutate input).
+ */
+export function applyHeartbeatWorkaround(req) {
+    if (isHeartbeatWorkaroundDisabled())
+        return req;
+    if (!isHeartbeatRequest(req))
+        return req;
+    const heartbeatModel = req.heartbeat?.model
+        ?? req.metadata?.heartbeat?.model
+        ?? HEARTBEAT_FALLBACK_MODEL;
+    return { ...req, model: heartbeatModel };
+}
+//# sourceMappingURL=heartbeat-workaround.js.map

package/dist/src/lib/heartbeat-workaround.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-workaround.js","sourceRoot":"","sources":["../../../src/lib/heartbeat-workaround.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAE3D,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,eAAe,EAAE,gBAAgB,EAAE,eAAe,CAAU,CAAC;AAUjG;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,IAAI,GAAG,CAAC,SAAS,EAAE,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,GAAG,CAAC,QAAQ,EAAE,SAAS;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,GAAG,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC/B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBACpC,KAAK,MAAM,QAAQ,IAAI,mBAAmB,EAAE,CAAC;oBAC3C,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;wBAAE,OAAO,IAAI,CAAC;gBAClD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAsB;IAC7D,IAAI,6BAA6B,EAAE;QAAE,OAAO,GAAG,CAAC;IAChD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IACzC,MAAM,cAAc,GAAG,GAAG,CAAC,SAAS,EAAE,KAAK;WACrC,GAAG,CAAC,QAAQ,EAAE,SAA4C,EAAE,KAAK;WAClE,wBAAwB,CAAC;IAC9B,OAAO,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;AAC3C,CAAC"}

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

@@ -0,0 +1,8 @@
+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 './route-flag.js';
+export { isTestMode, TEST_MODE_ENV, _setTestModeForTests } from './test-mode.js';
+export { getAggressiveStripEnabled, getCacheParityEnabled, getLogLevel, isLogLevelDebug, } from './config.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC3G,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,KAAK,MAAM,EACX,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,WAAW,EACX,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/src/lib/index.js

@@ -0,0 +1,8 @@
+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';
+export { selectEngine, isCcOpenclawEnabled, captureSessionRoute, ACTIVE_FLAG_ENV, ROUTE_FLAG_ENV, } from './route-flag.js';
+export { isTestMode, TEST_MODE_ENV, _setTestModeForTests } from './test-mode.js';
+export { getAggressiveStripEnabled, getCacheParityEnabled, getLogLevel, isLogLevelDebug, } from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/src/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAuC,MAAM,sBAAsB,CAAC;AAC3G,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,GAEd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,cAAc,GAGf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,WAAW,EACX,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/src/lib/register-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Centralized register-guard — eliminates listener stacking systemwide.
+ * Each plugin module gets its own guard instance via createRegisterGuard().
+ * Multiple register() calls with same id → no-op (regardless of api identity).
+ *
+ * Rationale (revised 2026-04-29 after observed production stacking):
+ * The openclaw gateway calls plugin register() multiple times per process —
+ * once per plugin context (gateway thread, per-agent thread). Each context
+ * passes a different `api` instance, but every api wraps the SAME shared
+ * event bus. Calling `api.on('event', fn)` from any api instance adds `fn`
+ * to that shared bus. So if we re-fire register body on each "new api",
+ * listeners stack N× → duplicate emissions (e.g. doubled-greeting on /new
+ * with 3 register cycles producing 3 sendMessage calls per reply).
+ *
+ * Previous behavior: tracked by (id, api) pair — re-fired on new api.
+ * Rationale was "hot-reload should re-wire" but that's not what happens
+ * in production; production gets multi-context registration in one process.
+ *
+ * Current behavior: track by id only. First register fires body; subsequent
+ * registers (any api) skip. Use `_resetForTests()` to clear between tests.
+ *
+ * Telemetry: when OPENCLAW_REGISTER_DEBUG=1, emits a structured event per
+ * register call (id, registered_before, timestamp). Sibling agent
+ * cco-hardening-B implements telemetry.ts which consumes these events.
+ */
+export interface RegisterGuard {
+    /** Wraps the actual register body — only runs once per (id, api) pair. */
+    guard(id: string, api: unknown, body: () => void): void;
+    /** Test-only reset. */
+    _resetForTests(): void;
+    /** Inspector for tests / telemetry. */
+    isRegistered(id: string): boolean;
+}
+export declare function createRegisterGuard(): RegisterGuard;
+/** Default singleton — most modules import this directly for simplicity. */
+export declare const defaultRegisterGuard: RegisterGuard;
+/**
+ * `registerOnce(id, api, body)` — preferred shorthand for the v3 §5 hard-rule
+ * contract: every `api.on(...)` call site must live inside an idempotency
+ * wrapper. Delegates to `defaultRegisterGuard.guard(id, api, body)` —
+ * semantically identical, just shorter at call sites.
+ *
+ * The CI check `scripts/check-register-once.sh` greps for any `api.on(`
+ * line whose containing module does NOT also reference `registerOnce` or
+ * `defaultRegisterGuard.guard`. Either form passes; bare `api.on()` calls
+ * (no idempotency wrapper) fail.
+ */
+export declare function registerOnce(id: string, api: unknown, body: () => void): void;
+//# sourceMappingURL=register-guard.d.ts.map

package/dist/src/lib/register-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-guard.d.ts","sourceRoot":"","sources":["../../../src/lib/register-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACxD,uBAAuB;IACvB,cAAc,IAAI,IAAI,CAAC;IACvB,uCAAuC;IACvC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CA8BnD;AAED,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,eAAwB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAE7E"}