pi-mega-compact 0.11.3 → 0.11.5

package/dist/extensions/mega-events/error-classifier.js

@@ -23,49 +23,48 @@
  *  - `etimedout` is Node's timeout errno lowercased — does NOT contain the
  *    substring "timeout".
  *  - `socket hang up` is Node's ECONNRESET *message*; the errno lives in
- *    error.code, which extractErrorSignature never sees. */
-export const KNOWN_RETRYABLE_TRANSIENT_PATTERN = /max(imum)? output token|rate[\s.-]?limit|429|too many requests|overloaded|5\d\d|internal server|bad gateway|service unavailable|network|time(?:d[\s-]?out|out)|etimedout|econnreset|econnrefused|epipe|eai_again|socket hang up|premature close|other side closed|connection (lost|refused|reset|aborted?)|stream (interrupted|closed|ended|failed)|disconnected/;
+ *    error.code, which extractErrorSignature never sees.
+ *  - router phrasings (all targets failed / no healthy target / too many
+ *    concurrent) -- pi's status prefix is console-only (2026-07-30 incident). */
+export const KNOWN_RETRYABLE_TRANSIENT_PATTERN = /max(imum)? output token|rate[\s.-]?limit|429|too many requests|too many concurrent|overloaded|5\d\d|internal server|bad gateway|service unavailable|all targets failed|no healthy target|fetch failed|network|time(?:d[\s-]?out|out)|etimedout|econnreset|econnrefused|epipe|eai_again|socket|closed unexpectedly|premature close|other side closed|connection (lost|refused|reset|aborted?|was closed)|stream (interrupted|closed|ended|failed)|disconnected/;
 /** R7: true when the error text carries a known-retryable transient marker.
  *  Defensively lowercases so callers can pass raw or normalized text. */
 export function isKnownRetryableTransient(text) {
     return KNOWN_RETRYABLE_TRANSIENT_PATTERN.test(text.toLowerCase());
 }
-/** S38.2: classify a turn-end error/stop signal into a retry category.
- *
- * `length` is returned as null — S28 owns the max-output-token length stopReason
- * exclusively (its agent_end nudge path is separate and must not be doubled).
- *
- * @param message  the event.message (a pi AgentMessage) or an error string
- * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | 'cancelled' | 'poisoned-context' | null (success/unknown)
- */
-export function classifyError(message) {
-    // Resolve a searchable text blob from a pi AgentMessage or raw string.
+/** R8: best-effort extraction of HTTP status from pi AgentMessage shapes. */
+function extractHttpStatus(m) {
+    for (const outer of [m.error, m]) {
+        if (!outer || typeof outer !== 'object')
+            continue;
+        for (const key of ['status', 'statusCode', 'code']) {
+            const v = outer[key];
+            if (typeof v === 'number' && v >= 100 && v <= 599)
+                return v;
+        }
+    }
+    return undefined;
+}
+/** R11: classify a turn-end error/stop signal into a retry category with a
+ *  diagnostic signal tag naming the rule that fired, plus the raw httpStatus
+ *  when extractHttpStatus found one. */
+export function classifyErrorDetailed(message) {
     let text = '';
-    // R3: usage-token signal. Only when `usage` is explicitly present with
-    // inputTokens=0 AND outputTokens=0 do we know the turn never reached the
-    // model. An ABSENT usage field means "unknown" (the event didn't carry
-    // token counts) — we do NOT treat that as the 0-token poisoned signal,
-    // because mid-response stream deaths and partial-content turns routinely
-    // omit usage while still being transient (preserves all pre-R3 tests).
     let usagePresent = false;
     let totalTokens = 0;
+    let httpStatus;
     if (typeof message === 'string') {
         text = message;
     }
     else if (message && typeof message === 'object') {
         const m = message;
         const sr = typeof m.stopReason === 'string' ? m.stopReason : '';
-        // S28 guard: length stopReason is handled exclusively by the S28 path.
         if (sr === 'length')
-            return null;
-        // User ESC / Ctrl-C abort — stopReason === 'aborted'. Not retryable:
-        // nudging would restart a task the user explicitly stopped.
+            return { category: null, signal: 'length-guard' };
         if (sr === 'aborted')
-            return 'cancelled';
-        // Success / normal tool flow — not an error, nothing to retry.
-        if (sr === 'stop' || sr === 'toolUse' || sr === 'tool_use')
-            return null;
-        // R3: extract usage tokens for the 0-token poisoned-context signal.
+            return { category: 'cancelled', signal: 'cancelled' };
+        if (/^(stop|tool_?use|end_?turn|max_?tokens|complete|finished|done)$/i.test(sr))
+            return { category: null, signal: 'success' };
         const usage = m.usage;
         usagePresent = usage != null && typeof usage === 'object';
         if (usagePresent) {
@@ -74,6 +73,7 @@ export function classifyError(message) {
                 (typeof u.inputTokens === 'number' ? u.inputTokens : 0) +
                     (typeof u.outputTokens === 'number' ? u.outputTokens : 0);
         }
+        httpStatus = extractHttpStatus(m);
         const parts = [];
         if (sr)
             parts.push(sr);
@@ -88,128 +88,86 @@ export function classifyError(message) {
             }
         }
         if (m.error) {
-            // Extract message from error objects for pattern matching.
             const err = m.error;
-            if (typeof err === 'string') {
+            if (typeof err === 'string')
                 parts.push(err);
-            }
             else if (err && typeof err === 'object') {
                 const errObj = err;
-                if (typeof errObj.message === 'string') {
+                if (typeof errObj.message === 'string')
                     parts.push(errObj.message);
-                }
-                else {
+                else
                     parts.push(JSON.stringify(err));
-                }
             }
         }
-        // S38: detect mid-response errors where the stream died without a
-        // proper stopReason (empty/undefined) — this catches provider failures
-        // that cut off the response mid-stream, INCLUDING the case where the
-        // provider emitted partial content before dying (a truncated response
-        // with no stop reason is a mid-stream death, not a success).
-        // A genuine success ALWAYS carries stop/tool_use/toolUse (which
-        // short-circuit to null at the top), so any message reaching here with a
-        // falsy stopReason is a stream failure → retryable.
         if (!sr) {
-            return 'transient';
+            // A missing stopReason alone is not sufficient evidence of stream death.
+            // Require at least one corroborating signal: an error field, or 0 total tokens
+            // (indicating the stream died before producing anything). A normal completion
+            // from a runtime that omits stopReason has content and tokens — not an error.
+            const hasError = (m.error != null && m.error !== undefined && m.error !== '') ||
+                (typeof m.errorMessage === 'string' && m.errorMessage !== '');
+            if (hasError || (usagePresent && totalTokens === 0)) {
+                const r = { category: 'transient', signal: 'stream-death-no-stopreason' };
+                if (httpStatus !== undefined)
+                    r.httpStatus = httpStatus;
+                return r;
+            }
+            // No stopReason, no error field, tokens present — likely a normal completion
+            // from a runtime that omits stopReason (pi-crew, etc.). Not an error.
+            return { category: null, signal: 'success' };
         }
         text = parts.join(' ');
     }
     if (!text)
-        return null;
+        return { category: null, signal: 'unknown' };
     const s = text.toLowerCase();
-    // --- compaction-noop (ORDER FIRST: pi race / manual compact catch) ---
-    // FAIL-2026071701: these are NOT retryable — the compaction already
-    // succeeded via pi's native path; retrying would race again.
-    if (/already compacted/.test(s))
-        return 'compaction-noop';
-    if (/compaction failed/.test(s))
-        return 'compaction-noop';
-    if (/nothing to compact/.test(s))
-        return 'compaction-noop';
-    if (/auto[\s-]?compaction failed/.test(s))
-        return 'compaction-noop';
-    // --- context-overflow (ORDER BEFORE generic transient!) ---
-    // A 400 from the model meaning "the prompt is bigger than the context window."
-    // Catches BOTH provider phrasings so the classification does not depend on
-    // which backend the router landed on:
-    //   - pi/Anthropic wrapper: "too long for this model's context window even
-    //     after compaction. Reduce the conversation length..." ->
-    //     too long | context window | even after compaction | reduce the conversation
-    //   - OpenAI/OpenRouter provider-side (often wrapped in "All targets failed:
-    //     <model>. Last error: ..."): "This model's maximum context length is N
-    //     tokens. Your request requires at least M tokens. Please reduce your
-    //     input or max_tokens." -> maximum context length | context length
-    //     exceeded | requires at least N tokens | reduce your input
-    // All of these carry `invalid_request_error` (UNDERSCORE, not 'invalid
-    // request' space) and would otherwise fall through to the generic
-    // `s.includes('error')` transient branch below, misclassifying as
-    // 'transient' and firing up to 5 blind retry nudges that re-submit the same
-    // oversized prompt -> re-400 -> busy-loop. 'context-overflow' instead forces
-    // ONE deferred re-compact (debounce-bypassed, race-guarded) and fires NO
-    // blind retry nudge. The forced re-compact is shaped by the existing
-    // session_before_compact durable trim (it cannot lower pi's firstKeptEntryId).
+    if (/already compacted|compaction failed|nothing to compact|auto[\s-]?compaction failed/.test(s)) {
+        return { category: 'compaction-noop', signal: 'compaction-noop' };
+    }
     if (/too long|context window|maximum context length|context length exceeded|requires at least \d+ tokens|even after compaction|reduce the conversation|reduce your input/.test(s)) {
-        return 'context-overflow';
+        return { category: 'context-overflow', signal: 'context-overflow' };
+    }
+    if (isKnownRetryableTransient(s)) {
+        const r = { category: 'transient', signal: 'transient-marker' };
+        if (httpStatus !== undefined)
+            r.httpStatus = httpStatus;
+        return r;
+    }
+    if (httpStatus === 429 || (httpStatus !== undefined && httpStatus >= 500)) {
+        return { category: 'transient', signal: 'transient-status', httpStatus };
+    }
+    if (httpStatus === 401 || httpStatus === 403) {
+        return { category: 'permanent', signal: 'permanent-status', httpStatus };
     }
-    // --- transient (known-retryable markers FIRST — these override poisoned signals) ---
-    // R3: network/throughput failures (timeout, ECONNRESET, 5xx, 429) MUST stay
-    // transient even when usage is 0 tokens, because they are retryable and
-    // /clear cannot fix them. 'connection aborted' is a network failure
-    // (ECONNABORTED), NOT a user ESC (stopReason 'aborted', early-return above).
-    // The marker set is shared with the agent-handlers R3 repeat-upgrade guard
-    // (isKnownRetryableTransient) so the two never drift.
-    if (isKnownRetryableTransient(s))
-        return 'transient';
-    // --- poisoned-context (R3: ORDER AFTER specific transient markers, BEFORE
-    // the generic 'error' transient fallthrough) ---
-    // A DETERMINISTIC request-rejection that retrying cannot fix. Re-submitting
-    // the same prompt re-triggers the same rejection. The 2026-07-28 incident
-    // was a provider returning 0-token "Request failed — please retry." turns
-    // for every request; classifyError mapped stopReason 'error' → 'transient'
-    // and the session emitted ~9 nudge bursts (~60 context-bloating messages)
-    // before stopping.
-    //
-    // Signal 1: provider request-validation 400 that is NOT context-overflow
-    // (context-overflow already returned above). Orphaned tool result / malformed
-    // message structure / unexpected role ordering / empty content. These were
-    // previously classified 'permanent' (max 1 retry) — but a single retry
-    // re-submits the SAME malformed structure and re-400s, so they are poisoned,
-    // not permanent. Auth/permission 400s stay permanent (separate check below).
     if (/invalid_request_error|invalid request|malformed|bad request|orphaned tool|tool (result )?(without|for )|unexpected role|role (ordering|sequence)|empty (content|message|request)/.test(s)) {
-        return 'poisoned-context';
+        return { category: 'poisoned-context', signal: 'poisoned-invalid-request' };
     }
-    // Signal 2: generic catch-all "request failed" / "request error" with no
-    // specific transient marker (transient markers already returned above).
-    // This is the exact phrasing the 2026-07-28 incident used. Without a
-    // specific retryable cause, treat the rejection as deterministic.
     if (/request failed|request error/.test(s)) {
-        return 'poisoned-context';
+        return { category: 'poisoned-context', signal: 'poisoned-request-failed' };
     }
-    // Signal 3: stopReason 'error' + usage explicitly 0 tokens (the turn never
-    // reached the model). Conservative: only when `usage` is PRESENT and 0 — an
-    // absent usage field means "unknown" and stays transient (mid-response
-    // deaths / partial-content turns often omit usage). The transient markers
-    // above already returned, so reaching here with 'error' text and 0 tokens
-    // means the request was rejected before any model work.
     if (usagePresent && totalTokens === 0 && /error/.test(s)) {
-        return 'poisoned-context';
+        return { category: 'transient', signal: 'bare-0-token' };
     }
-    // --- transient (generic 'error' stopReason fallthrough) ---
-    // Reaches here for a generic stopReason 'error' with no specific marker and
-    // no 0-token signal (usage absent or > 0). Stays transient — conservative.
     if (s.includes('error') && !/\b(auth|unauthorized|invalid (api )?key|permission)\b/.test(s)) {
-        return 'transient'; // generic pi stopReason 'error'
+        return { category: 'transient', signal: 'generic-error' };
+    }
+    if (/auth|unauthorized|invalid (api )?key|permission/.test(s)) {
+        return { category: 'permanent', signal: 'permanent-auth' };
     }
-    // NOTE: 'aborted' stopReason is handled by the sr==='aborted' early-return above.
-    // The text-based s.includes('aborted') was removed — it was the old path that
-    // misclassified user ESC/Ctrl-C as 'transient' (5 retry nudges after cancel).
-    // --- permanent (NOT retryable beyond 1) ---
-    if (/auth|unauthorized|invalid (api )?key|permission/.test(s))
-        return 'permanent';
-    // Unknown — do not retry (avoid busy-looping on an unclassified signal).
-    return null;
+    return { category: null, signal: 'unknown' };
+}
+/** S38.2: classify a turn-end error/stop signal into a retry category.
+ *
+ * `length` is returned as null — S28 owns the max-output-token length stopReason
+ * exclusively (its agent_end nudge path is separate and must not be doubled).
+ *
+ * Thin wrapper around classifyErrorDetailed — returns only the category.
+ *
+ * @param message  the event.message (a pi AgentMessage) or an error string
+ * @returns 'transient' | 'permanent' | 'compaction-noop' | 'context-overflow' | 'cancelled' | 'poisoned-context' | null (success/unknown)
+ */
+export function classifyError(message) {
+    return classifyErrorDetailed(message).category;
 }
 /** S38.2: exponential backoff for error-retry nudges.
  *  count is 1-based (the retry about to fire). baseMs is the unit
@@ -230,10 +188,33 @@ export function errorRetryBackoffMs(count, baseMs = 5000) {
  *  'error' for retryable turns) so two turns with the same error content share
  *  a signature. Empty string when there is no error text (e.g. a bare
  *  stopReason 'error' with no content) — the caller skips repeat detection in
- *  that case (the stateless 0-token signal handles bare errors). */
+ *  that case (the stateless 0-token signal handles bare errors).
+ *
+ *  R9: when the joined text is empty AND stopReason is 'error' AND usage is
+ *  present with 0 total tokens, returns the constant "bare-0-token-error" so
+ *  the repeat detector can corroborate bare 0-token errors (first turn is
+ *  transient; repeated occurrences upgrade to poisoned at threshold). Bare
+ *  'error' WITHOUT usage keeps returning '' (absent usage = unknown; mid-
+ *  response deaths stay out of repeat tracking). */
+/** R12: normalize volatile tokens in an already-lowercased error string so that
+ *  equivalent errors with varied model aliases, IPs, hex request-ids, retry
+ *  counts, and long numeric ids produce the same signature.  Order matters.
+ *  3-digit HTTP status codes (429/500/502/etc.) survive — the long-number rule
+ *  only covers 4+ digits.  Invariant: normalizeVolatileTokens never empties a
+ *  non-empty string (every regex replaces with a non-empty literal token). */
+function normalizeVolatileTokens(s) {
+    let n = s;
+    n = n.replace(/\b\d{1,3}(\.\d{1,3}){3}(:\d+)?\b/g, '<ip>'); // 1. IP:port / bare IPv4
+    n = n.replace(/\b[\w-]+(\/[\w.:+-]+)+/g, '<model>'); // 2. slash-separated paths
+    n = n.replace(/\b[0-9a-f]{8,}\b/g, '<hex>'); // 3. hex ids (8+ chars)
+    n = n.replace(/\b\d{4,}\b/g, '<n>'); // 4. long numbers (4+ digits)
+    n = n.replace(/\bafter \d+ attempts?\b/g, 'after <n> attempts'); // 5. attempt phrasing
+    n = n.replace(/\s+/g, ' ').trim(); // 6. collapse whitespace
+    return n;
+}
 export function extractErrorSignature(message) {
     if (typeof message === 'string')
-        return message.toLowerCase().trim();
+        return normalizeVolatileTokens(message.toLowerCase().trim());
     if (!message || typeof message !== 'object')
         return '';
     const m = message;
@@ -260,5 +241,14 @@ export function extractErrorSignature(message) {
                 parts.push(JSON.stringify(err));
         }
     }
-    return parts.join(' ').toLowerCase().trim();
+    const joined = parts.join(' ').toLowerCase().trim();
+    const normalized = normalizeVolatileTokens(joined);
+    if (normalized === '' &&
+        m.stopReason === 'error' &&
+        m.usage &&
+        typeof m.usage === 'object' &&
+        (m.usage.inputTokens ?? 0) + (m.usage.outputTokens ?? 0) === 0) {
+        return 'bare-0-token-error';
+    }
+    return normalized;
 }

package/dist/extensions/mega-events/mirror-append.js

@@ -0,0 +1,107 @@
+import { appendRawTranscript } from "../../src/store/sqlite.js";
+import { computeContentDigest } from "../../src/dedup/digest.js";
+import { ensureHwmTable, readHwm, writeHwm, dropHwm, } from "./context-hwm.js";
+/**
+ * Append incoming messages to raw_transcript with HWM incremental support.
+ *
+ * On fork/rewind (shorter message list or boundary hash mismatch), the HWM
+ * is dropped and all messages are reprocessed.
+ */
+export function appendMirrorMessages(db, messages, sessionId, epochId, currentTurn) {
+    ensureHwmTable(db);
+    const hwm = readHwm(db, sessionId);
+    let tailStart = 0;
+    let needDrop = false;
+    if (hwm) {
+        if (messages.length <= hwm.lastSeq) {
+            // Session was shortened (fork/rewind/clear) — full reprocess.
+            needDrop = true;
+        }
+        else {
+            // Verify boundary integrity: hash of message at hwm.lastSeq-1
+            // must match the stored hash.
+            const boundaryMsg = messages[hwm.lastSeq - 1];
+            const boundaryHash = contentHashOf(boundaryMsg.content);
+            if (boundaryHash === hwm.lastContentHash) {
+                tailStart = hwm.lastSeq;
+            }
+            else {
+                needDrop = true;
+            }
+        }
+    }
+    if (needDrop) {
+        dropHwm(db, sessionId);
+    }
+    // Process tail (or all if tailStart === 0).
+    let rowsProcessed = 0;
+    for (let i = tailStart; i < messages.length; i++) {
+        const raw = toRawRow(messages[i], sessionId, epochId, currentTurn);
+        if (raw) {
+            appendRawTranscript(db, raw);
+            rowsProcessed++;
+        }
+    }
+    // Write new HWM.
+    if (messages.length > 0) {
+        const lastMsg = messages[messages.length - 1];
+        writeHwm(db, {
+            sessionId,
+            lastSeq: messages.length,
+            lastContentHash: contentHashOf(lastMsg.content),
+        });
+    }
+    return { rowsProcessed };
+}
+/** Single rule for hashing message content on BOTH sides of the HWM
+ *  (write + boundary check) — a mismatch here silently defeats the
+ *  incremental path (every event would full-reprocess). null/undefined → "". */
+function contentHashOf(content) {
+    if (content == null)
+        return "";
+    const bytes = typeof content === "string"
+        ? content
+        : JSON.stringify(canonicalize(content));
+    return computeContentDigest(bytes).contentHash;
+}
+/**
+ * Canonicalize a value for deterministic JSON serialization (keys sorted).
+ * This is the same logic as the inline function in context-handler.ts.
+ */
+function canonicalize(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const sorted = Object.keys(value).sort();
+    const out = {};
+    for (const k of sorted) {
+        out[k] = canonicalize(value[k]);
+    }
+    return out;
+}
+/** Convert an AgentMessage to a RawTranscriptRow (same logic as toRawTranscriptRow in context-handler.ts). */
+function toRawRow(msg, sessionId, epochId, currentTurn) {
+    const m = msg;
+    const content = m.content;
+    if (content == null || content === "")
+        return null;
+    const contentBytes = typeof content === "string"
+        ? content
+        : JSON.stringify(canonicalize(content));
+    return {
+        contentHash: computeContentDigest(contentBytes).contentHash,
+        sessionId,
+        seq: 0, // assigned by appendRawTranscript
+        role: m.role ?? "unknown",
+        contentBytes,
+        toolName: m.toolName ?? null,
+        messageTimestamp: m.timestamp ?? null,
+        checkpointEpoch: epochId,
+        turnIndex: currentTurn ?? null,
+    };
+}
+// Re-export for convenience when the handler only needs the table ensure.
+export { ensureHwmTable, readHwm, writeHwm, dropHwm };

package/dist/extensions/mega-events/outage-advisor.js

@@ -0,0 +1,59 @@
+/**
+ * outage-advisor.ts — R10: calm "provider outage" advisory.
+ *
+ * When a provider/router flaps (transient errors: timeouts, 5xx, 429s),
+ * the extension retries silently and eventually goes quiet after caps. This
+ * module sends ONE user-facing advisory per outage episode so the user knows
+ * to wait rather than running /clear.
+ *
+ * Distinct from the poisoned-context /clear advise: the outage advisory is
+ * for transient errors where the user's context is fine.
+ *
+ * PREVENT-PI-003: sends via safeSendUserMessage (user-role only).
+ * PREVENT-PI-004: local ctx call, no network.
+ */
+import { safeSendUserMessage } from "./send-safe.js";
+/**
+ * Check the provider-outage advisory condition and fire once per episode.
+ *
+ * Called from the transient/permanent retry branch of the turn_end handler,
+ * AFTER consecutiveErrors is incremented.
+ *
+ * @param effectiveCategory — must be "transient" for the advisory to fire.
+ * @param runtime   — the live MegaRuntime (mutated on advisory fire).
+ * @param pi        — pi ExtensionAPI for safeSendUserMessage.
+ * @param config    — providerOutageAdviseThreshold config.
+ * @param detail    — R11: optional signal + rawText for forensics.
+ */
+export async function maybeSendProviderOutageAdvisory(effectiveCategory, runtime, pi, config, detail) {
+    if (effectiveCategory !== "transient")
+        return;
+    if (config.providerOutageAdviseThreshold <= 0)
+        return;
+    if (runtime.rt.providerOutageAdvised)
+        return;
+    if (runtime.rt.consecutiveErrors < config.providerOutageAdviseThreshold)
+        return;
+    runtime.rt.providerOutageAdvised = true;
+    runtime.dashboard.event("provider_outage_advised", {
+        consecutiveErrors: runtime.rt.consecutiveErrors,
+        turnIndex: runtime.currentTurn,
+        sessionId: runtime.rt.sessionId,
+        ...(detail?.signal !== undefined ? { signal: detail.signal } : {}),
+        ...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
+    });
+    runtime.logger.info("provider-outage-advised", {
+        sessionId: runtime.rt.sessionId,
+        consecutiveErrors: runtime.rt.consecutiveErrors,
+        turnIndex: runtime.currentTurn,
+        ...(detail?.signal !== undefined ? { signal: detail.signal } : {}),
+        ...(detail?.rawText !== undefined ? { rawText: detail.rawText } : {}),
+    });
+    // Advisory is dashboard-only (events tab + log). No user-visible message —
+    // injecting into the conversation scares users and triggers false-positive
+    // re-classification of the resulting turn (2026-07-31 incident).
+    if (!config.advisoryChannel) {
+        // Legacy path (flag OFF): user-role message injection.
+        await safeSendUserMessage(pi, `[mega-compact] the provider is having issues (${runtime.rt.consecutiveErrors} consecutive failures — timeouts/5xx/rate-limits). Retries are bounded and continue automatically; your context is fine — do NOT clear or reset it. Work resumes as soon as the provider recovers.`);
+    }
+}

package/dist/extensions/mega-events/perf-handler.js

@@ -1,10 +1,44 @@
 import { recordPerfSample } from "../../src/store/sqlite.js";
+import { classifyPrefixBreak } from "../../src/prefix-break.js";
 /** Narrow a turn_end message to its usage block when it is an assistant msg. */
 function usageOf(msg) {
     if (msg.role !== "assistant" || !msg.usage)
         return null;
     return msg.usage;
 }
+/**
+ * Attempt to record a prefix_break sample when a significant cache_hit_pct
+ * drop is detected between two consecutive turns.
+ *
+ * Drop threshold: 20 percentage points.  When triggered, calls
+ * classifyPrefixBreak with the three candidate event timestamps from the
+ * runtime and records a `prefix_break` sample.  Best-effort + non-fatal.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite write only.
+ * PREVENT-002: SQL is fully parameterized via recordPerfSample.
+ */
+function tryRecordPrefixBreak(stateDir, prevHitPct, currHitPct, breakAt, runtime) {
+    try {
+        if (prevHitPct - currHitPct < 20)
+            return; // no significant drop
+        const events = {
+            lastRecallAt: runtime.rt.lastInjectAt, // S53: inject fires alongside recall
+            lastCompactAt: runtime.rt.lastCompactAt,
+            lastInjectAt: runtime.rt.lastInjectAt,
+        };
+        const { cause, confidence } = classifyPrefixBreak(breakAt, events);
+        recordPerfSample(stateDir, "prefix_break", 0, {
+            cause,
+            confidence,
+            prevHitPct,
+            currHitPct,
+            breakAt,
+        }); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback perf instrumentation)
+    }
+    catch {
+        /* non-fatal: prefix-break detection never blocks the agent loop */
+    }
+}
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(pi, runtime) {
     // turn_start: record the wall-clock start of the turn. Using Date.now() (not
@@ -23,6 +57,7 @@ export function registerPerfHandler(pi, runtime) {
     });
     // turn_end: compute turn latency + TPS + cache hit % from the assistant
     // message's usage block. One perf_samples row per metric per turn.
+    // S53A: tracks prevHitPct across turns to detect prefix breaks.
     pi.on("turn_end", async (event) => {
         try {
             if (runtime.perfTurnStart > 0) {
@@ -36,7 +71,22 @@ export function registerPerfHandler(pi, runtime) {
                     recordPerfSample(runtime.currentStateDir, "tps", u.output / durSec, { outputTokens: u.output });
                     const denom = u.cacheRead + u.input + u.cacheWrite;
                     const hitPct = denom > 0 ? (u.cacheRead / denom) * 100 : 0;
-                    recordPerfSample(runtime.currentStateDir, "cache_hit_pct", hitPct, { input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite });
+                    recordPerfSample(runtime.currentStateDir, "cache_hit_pct", hitPct, {
+                        input: u.input,
+                        cacheRead: u.cacheRead,
+                        cacheWrite: u.cacheWrite,
+                        modelName: runtime.currentModel?.modelName,
+                        modelId: runtime.currentModel?.modelId,
+                    });
+                    // S53A: detect significant cache hit % drop → record prefix_break.
+                    // Only trigger when we have a previous value AND the drop is >20pp.
+                    if (runtime.rt._prevCacheHitPct != null &&
+                        runtime.rt._prevCacheHitPct - hitPct >= 20) {
+                        const breakAt = runtime.perfTurnStart;
+                        tryRecordPrefixBreak(runtime.currentStateDir, runtime.rt._prevCacheHitPct, hitPct, breakAt, runtime);
+                    }
+                    // Stamp for the next turn's comparison (even when no break fires).
+                    runtime.rt._prevCacheHitPct = hitPct;
                 }
             }
         }

package/dist/extensions/mega-events/recall-tail.js

@@ -0,0 +1,59 @@
+/**
+ * True when recall blocks are staged AND the feature flag is ON. Called by the
+ * context handler to decide whether to call withRecallTail.
+ */
+export function stagedForTail(runtime, config) {
+    if (!config.recallTailInject)
+        return false;
+    return (runtime.pendingRecallBlock != null ||
+        runtime.pendingMemoryRecallBlock != null);
+}
+/**
+ * Append staged recall/memory blocks as a single user-role message at the very
+ * tail of the messages array. Returns a NEW array (does not mutate input).
+ *
+ * Sets `runtime.recallInjectedThisTurn = true` when it actually appends, so the
+ * turn_end handler (agent-handlers.ts) consumes the staged blocks only if they
+ * reached a view this turn. If a turn ends with no context event, the flag
+ * stays false and the blocks remain staged for the next turn.
+ *
+ * Stable timestamp (runtime.perfTurnStart ?? Date.now()) so replays within the
+ * turn are byte-identical (mirrors the v0.8.6 summaryAgentMsg rationale).
+ *
+ * Non-fatal: on any failure, returns messages unmodified and does NOT set the
+ * injected flag. PREVENT-PI-003: the injected message has role "user", never
+ * "system".
+ */
+export function withRecallTail(messages, runtime, config) {
+    if (!config.recallTailInject)
+        return messages;
+    try {
+        const blocks = [];
+        if (runtime.pendingRecallBlock != null) {
+            blocks.push(runtime.pendingRecallBlock);
+        }
+        if (runtime.pendingMemoryRecallBlock != null) {
+            blocks.push(runtime.pendingMemoryRecallBlock);
+        }
+        if (blocks.length === 0)
+            return messages;
+        const tailText = blocks.join("\n\n");
+        const timestamp = runtime.perfTurnStart ?? // stable within a turn
+            Date.now();
+        const tailMsg = {
+            role: "user",
+            content: tailText,
+            timestamp,
+        };
+        runtime.rt.recallInjectedThisTurn = true;
+        // Append at the very tail — never splits toolCall/toolResult.
+        // PREVENT-PI-001/002: a single message appended after a complete
+        // transcript prefix cannot split a toolCall/toolResult pair.
+        return [...messages, tailMsg];
+    }
+    catch {
+        // Non-fatal: leave blocks staged (flag stays unset) and return the
+        // unmodified view. The context event still proceeds normally.
+        return messages;
+    }
+}

package/dist/extensions/mega-events/session-handlers.js

@@ -149,14 +149,21 @@ export function registerSessionHandlers(pi, runtime, config) {
         catch {
             /* non-fatal: intent polling never breaks the agent loop */
         }
-        const cpBlock = runtime.pendingRecallBlock;
-        const memBlock = runtime.pendingMemoryRecallBlock;
-        if (!cpBlock && !memBlock)
-            return;
-        runtime.pendingRecallBlock = undefined;
-        runtime.pendingMemoryRecallBlock = undefined;
-        const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
-        return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+        // S53: when recallTailInject is ON, the staged blocks are injected as a
+        // user-role tail message by the context handler (recall-tail.ts), NOT
+        // here. This prepend path is the legacy behavior (flag OFF = byte-
+        // identical pre-sprint). captureModel + rewind-intent consumption above
+        // stay unconditional regardless of the flag.
+        if (!config.recallTailInject) {
+            const cpBlock = runtime.pendingRecallBlock;
+            const memBlock = runtime.pendingMemoryRecallBlock;
+            if (!cpBlock && !memBlock)
+                return;
+            runtime.pendingRecallBlock = undefined;
+            runtime.pendingMemoryRecallBlock = undefined;
+            const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
+            return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+        }
     });
     pi.on("session_shutdown", async (_event, ctx) => {
         runtime.setStatus(ctx, undefined);