@aexol/spectral 0.9.220 → 0.9.222

package/dist/server/session-stream.js

@@ -38,115 +38,36 @@
  */
 import { randomUUID } from "node:crypto";
 import { AgentBridge } from "./agent-bridge.js";
-import { SettingsManager, } from "../sdk/coding-agent/index.js";
 import { InterAgentBroker } from "./inter-agent-broker.js";
 import { setInterAgentBroker } from "../memory/inter-agent-broker-singleton.js";
 import { configureFanout } from "./fanout/fanout-manager.js";
-import { CONTEXT_LIMIT_RATIO, DEFAULT_COMPACTION_POLICY, getAutoOlderHistoryContextThresholdTokens, } from "../sdk/coding-agent/core/compaction/policy.js";
-import { getMemoryState, isSourceEntry, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../memory/branch.js";
+import { getAutoOlderHistoryContextThresholdTokens } from "../sdk/coding-agent/core/compaction/policy.js";
+import { getMemoryState, rawTokensSinceLastBound, rawTokensSinceLastCompaction, } from "../memory/branch.js";
 import { observationPoolTokens, renderSummary } from "../memory/compaction.js";
 import { loadConfig } from "../memory/config.js";
 import { setProjectObsStore } from "../memory/project-observations-store.js";
 import { estimateStringTokens } from "../memory/tokens.js";
 import { reflectionContent, reflectionId, } from "../memory/types.js";
 import { humanizeProviderError } from "./error-humanizer.js";
-import { estimateImagesTokens, parseImagesJson, } from "./image-attachments.js";
-/**
- * Extract the `creditsUsed` value from a `token_usage` event embedded in an
- * events JSONL string. Returns `null` if no `token_usage` event is present
- * (e.g. it hasn't arrived yet at persist time — the race condition this
- * column exists to bridge). Best-effort: malformed lines are skipped.
- */
-function extractCreditsFromEventsJsonl(eventsJsonl) {
-    if (!eventsJsonl)
-        return null;
-    let creditsUsed = null;
-    for (const line of eventsJsonl.split("\n")) {
-        if (!line.includes("token_usage"))
-            continue;
-        try {
-            const ev = JSON.parse(line);
-            if (ev.type === "token_usage" &&
-                typeof ev.usage.creditsUsed === "number") {
-                creditsUsed = ev.usage.creditsUsed;
-            }
-        }
-        catch {
-            // Skip malformed lines — best-effort extraction.
-        }
-    }
-    return creditsUsed;
-}
+import { parseImagesJson } from "./image-attachments.js";
+// Focused helper modules extracted from this file (bodies moved verbatim;
+// names re-exported below so the public surface of session-stream.js is
+// unchanged).
+import { formatCompactionTokenStats, isSkippedCompactionResult, } from "./session-stream/compaction-events.js";
+import { getCompactionEndPruneSkipReason, prunePersistedHistoryAfterCompaction, } from "./session-stream/history-prune.js";
+import { applyDcpLiteRuntimeStatus, dcpLiteEventFromServerEvent, defaultMemoryStatus, loadCompactionPolicy, persistObservationalMemorySnapshot, } from "./session-stream/memory.js";
+import { selectHistoryForBridge } from "./session-stream/replay-tail.js";
+import { assistantMessageIdsForTurn, extractCreditsFromEventsJsonl, isReplayable, snapshotTurn, } from "./session-stream/turn-events.js";
+import { resolveTurnSilenceMaxRearm, resolveTurnSilenceTimeoutMs, } from "./session-stream/turn-silence.js";
+export { formatCompactionTokenStats, isSkippedCompactionResult, } from "./session-stream/compaction-events.js";
+export { branchMessageRole, branchMessageSignature, branchMessageTimestampMs, contentAsPersistedText, getCompactionEndPruneSkipReason, getKeptBranchMessageSignatures, isRecord, matchKeptPersistedMessageIds, prunePersistedHistoryAfterCompaction, selectUniqueCandidate, } from "./session-stream/history-prune.js";
+export { applyDcpLiteRuntimeStatus, buildDcpLiteThresholds, contextPercent, dcpLiteEventFromServerEvent, defaultMemoryStatus, loadCompactionPolicy, persistObservationalMemorySnapshot, } from "./session-stream/memory.js";
+export { estimateStoredMessageReplayTokens, selectHistoryForBridge, } from "./session-stream/replay-tail.js";
+export { assistantMessageIdsForTurn, extractCreditsFromEventsJsonl, isReplayable, snapshotTurn, } from "./session-stream/turn-events.js";
+export { resolveTurnSilenceMaxRearm, resolveTurnSilenceTimeoutMs, } from "./session-stream/turn-silence.js";
 const DEFAULT_BRIDGE_FACTORY = (args) => new AgentBridge(args);
 /** Safety limit for autonomous loop iterations per session. */
 const MAX_LOOP_ITERATIONS = 100;
-// Fix E: safety-net for stale `currentTurn`. When an agent hangs, crashes,
-// or the WS drops during sleep, `agent_end` may never arrive and
-// `stream.currentTurn` stays non-null forever. On reconnect, `session_ready`
-// then reports `currentTurn != null`, so landing shows a phantom "streaming"
-// status. This timer clears the stale turn and emits a synthetic `agent_end`
-// after 30 minutes of silence on streaming-meaningful events.
-//
-// Configurable via `SPECTRAL_TURN_SILENCE_TIMEOUT_MS`:
-//   * unset / empty / not-a-number / negative -> 30 minutes (default)
-//   * `0` -> DISABLED, the timer is never armed (official opt-out)
-//   * a positive fraction (e.g. `0.5`) is rounded UP to 1ms so it can never
-//     accidentally disable the safety net
-//   * anything larger than Node's max delay is clamped (see below)
-const DEFAULT_TURN_SILENCE_TIMEOUT_MS = 30 * 60 * 1000;
-/**
- * Node emits `TimeoutOverflowWarning` and fires immediately for delays above
- * this value, so anything larger is clamped to it.
- */
-const MAX_TIMEOUT_DELAY_MS = 2_147_483_647;
-/**
- * Upper bound on how many times the silence timer may be re-armed instead of
- * closing the turn while a subagent is still running. Guards against a
- * counter stuck at >0 forever (e.g. a `subagent_end` that never arrives after
- * a crash) turning the safety net off permanently.
- * `SPECTRAL_TURN_SILENCE_MAX_REARM=0` means unlimited re-arms.
- */
-const DEFAULT_TURN_SILENCE_MAX_REARM = 8;
-/**
- * Sanity clamp for `SPECTRAL_TURN_SILENCE_MAX_REARM`. Even with the shortest
- * useful timeout this is days of silence, so a typo like `1e10` cannot keep a
- * hung turn open effectively forever.
- */
-const MAX_TURN_SILENCE_MAX_REARM = 1000;
-function resolveTurnSilenceTimeoutMs() {
-    const raw = process.env.SPECTRAL_TURN_SILENCE_TIMEOUT_MS;
-    if (raw === undefined || raw.trim() === "") {
-        return DEFAULT_TURN_SILENCE_TIMEOUT_MS;
-    }
-    const parsed = Number(raw);
-    // `0` is the documented way to switch the safety net off entirely.
-    if (parsed === 0)
-        return 0;
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        return DEFAULT_TURN_SILENCE_TIMEOUT_MS;
-    }
-    // `Math.max(1, ...)`: a fractional value such as `0.5` must floor to 1ms,
-    // not to 0 — flooring to 0 would silently switch the safety net off.
-    return Math.min(Math.max(1, Math.floor(parsed)), MAX_TIMEOUT_DELAY_MS);
-}
-function resolveTurnSilenceMaxRearm() {
-    const raw = process.env.SPECTRAL_TURN_SILENCE_MAX_REARM;
-    // Empty / whitespace-only must NOT fall through to `Number(...)`, which
-    // coerces `""` to `0` and would therefore mean "unlimited re-arms" —
-    // i.e. the original "phantom streaming forever" bug.
-    if (raw === undefined || raw.trim() === "") {
-        return DEFAULT_TURN_SILENCE_MAX_REARM;
-    }
-    const parsed = Number(raw);
-    // `0` is the documented way to allow unlimited re-arms (opt-out of the
-    // re-arm budget).
-    if (parsed === 0)
-        return 0;
-    if (!Number.isFinite(parsed) || parsed < 0) {
-        return DEFAULT_TURN_SILENCE_MAX_REARM;
-    }
-    return Math.min(Math.max(1, Math.floor(parsed)), MAX_TURN_SILENCE_MAX_REARM);
-}
 // Streaming-meaningful events that reset the silence timer while a turn is
 // active. Mirrors Fix C on the landing side, but EXCLUDES `token_usage`
 // (arrives post-turn) and excludes terminal/control events handled by their
@@ -176,18 +97,6 @@ const STREAMING_MEANINGFUL_EVENT_TYPES = new Set([
     "subagent_tool_progress",
     "subagent_end",
 ]);
-/**
- * Defensive cap for fresh-bridge history replay when we already have a
- * persisted observational-memory snapshot. spectral's own compaction keeps a
- * recent live tail verbatim and summarizes the older prefix; replaying the
- * entire SQLite transcript after restart defeats that and can explode the
- * next prompt. We therefore rehydrate only an approximate recent tail.
- *
- * Keep this conservative — the tail is rehydrated as raw user/assistant
- * messages PLUS spectral reconstructs tool-result messages from events_jsonl,
- * so the actual context inflation is 3-8× the stored token estimate.
- */
-const REHYDRATION_TAIL_TOKEN_BUDGET = 20_000;
 const UI_HISTORY_TAIL_MESSAGE_LIMIT = 60;
 /**
  * Number of accumulated wire events before flushing the in-flight turn
@@ -197,367 +106,6 @@ const UI_HISTORY_TAIL_MESSAGE_LIMIT = 60;
 const BATCH_FLUSH_INTERVAL = 10;
 /** Marker the agent emits in its response to signal the task is complete. */
 const LOOP_DONE_MARKER = "<LOOP_DONE>";
-function persistObservationalMemorySnapshot(store, sessionId, bridge) {
-    if (!bridge.getSessionBranch)
-        return;
-    try {
-        const entries = bridge.getSessionBranch();
-        const memoryState = getMemoryState(entries);
-        const allObservations = [
-            ...memoryState.committedObs,
-            ...memoryState.pendingObs,
-        ];
-        const hasMemory = memoryState.reflections.length > 0 || allObservations.length > 0;
-        if (!hasMemory) {
-            store.deleteSessionMemorySnapshot(sessionId);
-            return;
-        }
-        const summary = renderSummary(memoryState.reflections, allObservations);
-        const details = {
-            type: "observational-memory",
-            version: 4,
-            observations: allObservations,
-            reflections: memoryState.reflections,
-        };
-        store.upsertSessionMemorySnapshot(sessionId, {
-            summary,
-            details,
-            coveredSourceCount: entries.filter((entry) => isSourceEntry(entry))
-                .length,
-        });
-    }
-    catch (err) {
-        console.warn(`[spectral] warn: failed to persist observational memory snapshot for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function estimateStoredMessageReplayTokens(message) {
-    return (estimateStringTokens(message.content) +
-        estimateStringTokens(message.events) +
-        estimateImagesTokens(message.images));
-}
-function formatCompactionTokenStats(event) {
-    const parts = [];
-    if (typeof event.compactionNumber === "number") {
-        parts.push(`compaction #${event.compactionNumber.toLocaleString()}`);
-    }
-    if (typeof event.tokensBefore === "number") {
-        parts.push(`from ~${event.tokensBefore.toLocaleString()} tokens`);
-    }
-    if (typeof event.tokensCompacted === "number") {
-        parts.push(`compacted ~${event.tokensCompacted.toLocaleString()} tokens`);
-    }
-    if (typeof event.tokensRemoved === "number") {
-        parts.push(`removed ~${event.tokensRemoved.toLocaleString()} tokens`);
-    }
-    if (typeof event.summaryTokens === "number") {
-        parts.push(`summary +~${event.summaryTokens.toLocaleString()} tokens`);
-    }
-    if (typeof event.reductionPercent === "number") {
-        parts.push(`reduction ~${event.reductionPercent.toLocaleString(undefined, { maximumFractionDigits: 2 })}%`);
-    }
-    if (event.largestTokenSources?.length) {
-        const sources = event.largestTokenSources
-            .slice(0, 3)
-            .map((bucket) => `${bucket.type}:${bucket.name} ~${bucket.tokens.toLocaleString()}`)
-            .join("; ");
-        parts.push(`largest sources ${sources}`);
-    }
-    return parts.length > 0 ? ` (${parts.join(", ")})` : "";
-}
-function isSkippedCompactionResult(result) {
-    return Boolean(result && typeof result === "object" && result.skipped === true);
-}
-// Persisted-history prune is deliberately stricter than timeline status
-// rendering: only a successful compaction_end proves Pi appended a usable
-// compaction entry. Aborted, skipped, or failed endings may leave the branch
-// unchanged or partially settled, so pruning must skip instead of guessing.
-function getCompactionEndPruneSkipReason(event) {
-    if (event.aborted)
-        return "aborted";
-    if (event.skipped)
-        return "skipped";
-    if (event.errorMessage)
-        return "failed";
-    if (typeof event.tokensRemoved !== "number" || event.tokensRemoved <= 0)
-        return "missing_token_reduction";
-    return null;
-}
-const BRANCH_MESSAGE_TIMESTAMP_TOLERANCE_MS = 5_000;
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function contentAsPersistedText(content) {
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return null;
-    const textParts = [];
-    for (const part of content) {
-        if (typeof part === "string") {
-            textParts.push(part);
-            continue;
-        }
-        if (isRecord(part) &&
-            part.type === "text" &&
-            typeof part.text === "string") {
-            textParts.push(part.text);
-        }
-    }
-    return textParts.length > 0 ? textParts.join("") : null;
-}
-function branchMessageTimestampMs(entry, message) {
-    if (typeof message.timestamp === "number" &&
-        Number.isFinite(message.timestamp))
-        return message.timestamp;
-    if (typeof entry.timestamp !== "string")
-        return null;
-    const parsed = Date.parse(entry.timestamp);
-    return Number.isFinite(parsed) ? parsed : null;
-}
-function branchMessageSignature(entry) {
-    if (entry.type !== "message" || !isRecord(entry.message))
-        return null;
-    const role = entry.message.role;
-    if (role !== "user" && role !== "assistant")
-        return null;
-    const content = contentAsPersistedText(entry.message.content);
-    if (content === null)
-        return null;
-    return {
-        role,
-        content,
-        timestampMs: branchMessageTimestampMs(entry, entry.message),
-        entryId: entry.id,
-    };
-}
-function branchMessageRole(entry) {
-    return entry.type === "message" && isRecord(entry.message)
-        ? entry.message.role
-        : undefined;
-}
-function getKeptBranchMessageSignatures(entries, keptEntryIndex) {
-    const signatures = [];
-    for (let i = keptEntryIndex; i < entries.length; i++) {
-        const entry = entries[i];
-        if (entry.type !== "message")
-            continue;
-        const role = branchMessageRole(entry);
-        if (role !== "user" && role !== "assistant")
-            continue;
-        const signature = branchMessageSignature(entry);
-        if (!signature) {
-            console.log(`[spectral] prune: skipped – reason=unsafe_kept_message, ` +
-                `kept branch message ${entry.id} cannot be matched safely`);
-            return null;
-        }
-        signatures.push(signature);
-    }
-    return signatures;
-}
-function selectUniqueCandidate(candidates, kept) {
-    if (candidates.length === 1)
-        return candidates[0];
-    if (kept.timestampMs === null)
-        return null;
-    const keptTimestampMs = kept.timestampMs;
-    const timestampMatches = candidates.filter((candidate) => Math.abs(candidate.message.createdAt - keptTimestampMs) <=
-        BRANCH_MESSAGE_TIMESTAMP_TOLERANCE_MS);
-    return timestampMatches.length === 1 ? timestampMatches[0] : null;
-}
-function matchKeptPersistedMessageIds(existing, keptBranchMessages) {
-    const existingConversationMessages = existing
-        .filter((message) => message.role === "user" || message.role === "assistant")
-        .map((message, conversationIndex) => ({ message, conversationIndex }));
-    const matchedIds = new Set();
-    let searchStart = 0;
-    for (const kept of keptBranchMessages) {
-        const candidates = existingConversationMessages.filter((candidate) => candidate.conversationIndex >= searchStart &&
-            !matchedIds.has(candidate.message.id) &&
-            candidate.message.role === kept.role &&
-            candidate.message.content === kept.content);
-        const selected = selectUniqueCandidate(candidates, kept);
-        if (!selected) {
-            console.log(`[spectral] prune: skipped – reason=ambiguous_kept_mapping, ` +
-                `could not stably match kept branch entry ${kept.entryId} ` +
-                `(${kept.role}, ${kept.content.length.toLocaleString()} chars) to SQLite history`);
-            return null;
-        }
-        matchedIds.add(selected.message.id);
-        searchStart = selected.conversationIndex + 1;
-    }
-    return matchedIds;
-}
-function loadCompactionPolicy(cwd) {
-    try {
-        return SettingsManager.create(cwd).getCompactionPolicy();
-    }
-    catch {
-        return DEFAULT_COMPACTION_POLICY;
-    }
-}
-function selectHistoryForBridge(history, hasMemorySnapshot) {
-    if (!history || history.length === 0)
-        return history;
-    if (!hasMemorySnapshot)
-        return history;
-    let total = 0;
-    let start = history.length - 1;
-    for (; start >= 0; start--) {
-        const nextTotal = total + estimateStoredMessageReplayTokens(history[start]);
-        if (total > 0 && nextTotal > REHYDRATION_TAIL_TOKEN_BUDGET)
-            break;
-        total = nextTotal;
-    }
-    const selected = history.slice(Math.max(0, start + 1));
-    return selected.length > 0 ? selected : [history[history.length - 1]];
-}
-function prunePersistedHistoryAfterCompaction(store, sessionId, bridge) {
-    if (!bridge.getSessionBranch)
-        return;
-    try {
-        const entries = bridge.getSessionBranch();
-        // Pi appends a CompactionEntry (type "compaction") at the end whose
-        // firstKeptEntryId marks the first branch entry that survives in LLM context.
-        // We scan backwards so we find the most recent compaction (there should be
-        // exactly one per compaction pass).
-        const lastCompaction = [...entries]
-            .reverse()
-            .find((entry) => entry.type === "compaction");
-        const firstKeptEntryId = lastCompaction?.firstKeptEntryId;
-        if (!firstKeptEntryId) {
-            console.log(`[spectral] prune: skipped – reason=missing_compaction_entry, ` +
-                `no compaction entry (or no firstKeptEntryId) ` +
-                `in branch for ${sessionId} (${entries.length} entries)`);
-            return;
-        }
-        const keptEntryIndex = entries.findIndex((entry) => entry.id === firstKeptEntryId);
-        if (keptEntryIndex === -1) {
-            console.log(`[spectral] prune: skipped – reason=missing_kept_entry, ` +
-                `firstKeptEntryId "${firstKeptEntryId}" ` +
-                `not found in ${entries.length} branch entries for ${sessionId}`);
-            return;
-        }
-        const keptBranchMessages = getKeptBranchMessageSignatures(entries, keptEntryIndex);
-        if (!keptBranchMessages)
-            return;
-        const existing = store.getMessages(sessionId);
-        if (existing.length === 0)
-            return;
-        if (keptBranchMessages.length === 0) {
-            console.log(`[spectral] prune: skipped – reason=no_kept_conversation_messages, ` +
-                `no kept persisted user/assistant messages for ${sessionId}`);
-            return;
-        }
-        console.log(`[spectral] prune: ${sessionId} – source=compaction_end, branch has ${entries.length} entries, ` +
-            `kept portion starts at index ${keptEntryIndex} (id=${firstKeptEntryId}), ` +
-            `${keptBranchMessages.length} user+assistant entries kept, ` +
-            `${existing.length} SQLite messages`);
-        const matchedKeptIds = matchKeptPersistedMessageIds(existing, keptBranchMessages);
-        if (!matchedKeptIds)
-            return;
-        const deleteIds = existing
-            .filter((message) => (message.role === "user" || message.role === "assistant") &&
-            !matchedKeptIds.has(message.id))
-            .map((message) => message.id);
-        if (deleteIds.length === 0) {
-            console.log(`[spectral] prune: skipped – reason=already_pruned, ` +
-                `SQLite history already matches compacted branch for ${sessionId}`);
-            return;
-        }
-        const pruned = store.deleteMessagesByIdForSession(sessionId, deleteIds);
-        console.log(`[spectral] prune: finished – reason=successful_compaction_end, ` +
-            `dropped ${pruned} pre-compaction message(s) ` +
-            `for ${sessionId}, ${matchedKeptIds.size} user/assistant message(s) kept`);
-    }
-    catch (err) {
-        console.warn(`[spectral] warn: failed to prune persisted history after compaction for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-function buildDcpLiteThresholds(config, policy) {
-    return {
-        postRunCompactionThresholdTokens: Math.max(config.compactionThresholdTokens, policy.autoOlderHistory.minRawTokens),
-        autoContextLimitRatio: CONTEXT_LIMIT_RATIO,
-        olderHistoryKeepRecentTokens: policy.agentDriven.olderHistoryKeepRecentTokens,
-        olderHistoryMinCompactableTokens: policy.agentDriven.olderHistoryMinCompactableTokens,
-        cooldownTurns: policy.agentDriven.cooldownTurns,
-    };
-}
-function contextPercent(usedTokens, maxTokens) {
-    if (typeof usedTokens !== "number" ||
-        typeof maxTokens !== "number" ||
-        maxTokens <= 0)
-        return null;
-    return Math.max(0, Math.min(100, (usedTokens / maxTokens) * 100));
-}
-function applyDcpLiteRuntimeStatus(status, stream) {
-    if (!status.dcpLite || !stream)
-        return;
-    const usage = stream.bridge.getContextUsage?.();
-    const usedTokens = usage ? usage.tokens : stream.contextWindowUsed;
-    const maxTokens = usage ? usage.contextWindow : stream.contextWindowMax;
-    const percent = usage?.percent ?? contextPercent(usedTokens, maxTokens);
-    if (usage || usedTokens !== null || maxTokens !== null) {
-        status.dcpLite.contextWindow = { usedTokens, maxTokens, percent };
-    }
-    if (stream.lastDcpEvent) {
-        status.dcpLite.lastEvent = stream.lastDcpEvent;
-    }
-}
-function dcpLiteEventFromServerEvent(event) {
-    if (event.type !== "agent_notification" || !event.dcpLiteTelemetry)
-        return null;
-    const telemetry = event.dcpLiteTelemetry;
-    return {
-        kind: telemetry.event,
-        message: event.message,
-        timestamp: telemetry.timestamp,
-        source: telemetry.source,
-        mode: telemetry.mode,
-        scope: telemetry.scope,
-        reason: telemetry.reason,
-        satisfiedSignals: telemetry.satisfiedSignals,
-        rawTokens: telemetry.rawTokens,
-        contextTokens: telemetry.contextTokens,
-        contextPercent: telemetry.contextPercent,
-        tokensBefore: telemetry.tokensBefore,
-        tokensAfter: telemetry.tokensAfter,
-        tokensRemoved: telemetry.tokensRemoved,
-    };
-}
-function defaultMemoryStatus(cwd) {
-    const config = loadConfig(cwd);
-    const policy = loadCompactionPolicy(cwd);
-    return {
-        mode: config.passive ? "passive" : "active",
-        phase: "idle",
-        inFlight: {
-            observer: false,
-            compaction: false,
-            reflection: false,
-            pruner: false,
-        },
-        reflections: { count: 0, tokens: 0 },
-        observations: {
-            committedCount: 0,
-            committedTokens: 0,
-            pendingCount: 0,
-            pendingTokens: 0,
-        },
-        thresholds: {
-            observation: config.observationThresholdTokens,
-            compaction: config.compactionThresholdTokens,
-            reflection: config.reflectionThresholdTokens,
-        },
-        progress: {
-            sinceObservationBoundTokens: 0,
-            sinceLastCompactionTokens: 0,
-            observationPoolTokens: 0,
-        },
-        dcpLite: {
-            thresholds: buildDcpLiteThresholds(config, policy),
-        },
-    };
-}
 export class SessionStreamManager {
     store;
     cwd;
@@ -2830,42 +2378,3 @@ export class SessionStreamManager {
         return true;
     }
 }
-function isReplayable(event) {
-    return (event.type === "message_start" ||
-        event.type === "text_delta" ||
-        event.type === "thinking_start" ||
-        event.type === "thinking_delta" ||
-        event.type === "thinking_end" ||
-        event.type === "tool_call" ||
-        event.type === "tool_result" ||
-        event.type === "message_end" ||
-        event.type === "token_usage" ||
-        event.type === "error" ||
-        event.type === "subagent_start" ||
-        // `subagent_progress` carries full accumulated live snapshots (streaming
-        // text/thinking/status) and is intentionally live-only; buffering it into
-        // currentTurn or batch persistence recreates O(n²) snapshot growth while a
-        // long subagent is running. Keep lifecycle/tool/end events replayable.
-        event.type === "subagent_end" ||
-        event.type === "subagent_tool_progress");
-}
-function assistantMessageIdsForTurn(turn) {
-    const ids = new Set();
-    for (const event of turn.events) {
-        if (event.type === "message_start")
-            ids.add(event.messageId);
-    }
-    return ids;
-}
-function snapshotTurn(turn, includePersistedEvents = false) {
-    // Defensive copy of the events array so the snapshot can't be mutated by
-    // subsequent buffer pushes. Individual event objects are safe to share —
-    // they're never mutated after creation.
-    return {
-        turnId: turn.turnId,
-        startedAt: turn.startedAt,
-        events: includePersistedEvents
-            ? [...turn.events]
-            : turn.events.slice(turn.persistedEventCount),
-    };
-}

package/dist/server/storage/observation-ranking.d.ts

@@ -0,0 +1,14 @@
+/** Minimum mean trigram Jaccard similarity for a typo-tolerant fallback match. */
+export declare const TYPO_FALLBACK_MIN_MEAN_SIMILARITY = 0.3;
+/**
+ * Trigram Jaccard similarity at or above which a new observation is treated
+ * as a near-duplicate rewording of an existing row and replaces it.
+ */
+export declare const NEAR_DUPLICATE_SIMILARITY = 0.9;
+/**
+ * Final ranking score for a candidate observation: a weighted blend of
+ * normalized text-match quality, relevance tag and recency decay. Every
+ * component is in [0, 1]; higher is better.
+ */
+export declare function scoreObservation(textScore: number, relevance: string, createdAt: number, now: number): number;
+//# sourceMappingURL=observation-ranking.d.ts.map

package/dist/server/storage/observation-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-ranking.d.ts","sourceRoot":"","sources":["../../../src/server/storage/observation-ranking.ts"],"names":[],"mappings":"AAiBA,kFAAkF;AAClF,eAAO,MAAM,iCAAiC,MAAM,CAAC;AACrD;;;GAGG;AACH,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,MAAM,CASR"}

package/dist/server/storage/observation-ranking.js

@@ -0,0 +1,37 @@
+// ---- observational-memory ranking constants ------------------------------
+/** Weight of the text-match component (bm25-derived or trigram similarity). */
+const WEIGHT_TEXT_MATCH = 0.6;
+/** Weight of the relevance-tag component (critical=1.0 … low=0.25). */
+const WEIGHT_RELEVANCE = 0.25;
+/** Weight of the recency component. */
+const WEIGHT_RECENCY = 0.15;
+/** Recency decay constant: exp(-ageDays / RECENCY_DECAY_DAYS). */
+const RECENCY_DECAY_DAYS = 30;
+const MS_PER_DAY = 86_400_000;
+/** Relevance-tag weights used by the ranking formula. */
+const RELEVANCE_WEIGHTS = {
+    critical: 1.0,
+    high: 0.75,
+    medium: 0.5,
+    low: 0.25,
+};
+/** Minimum mean trigram Jaccard similarity for a typo-tolerant fallback match. */
+export const TYPO_FALLBACK_MIN_MEAN_SIMILARITY = 0.3;
+/**
+ * Trigram Jaccard similarity at or above which a new observation is treated
+ * as a near-duplicate rewording of an existing row and replaces it.
+ */
+export const NEAR_DUPLICATE_SIMILARITY = 0.9;
+/**
+ * Final ranking score for a candidate observation: a weighted blend of
+ * normalized text-match quality, relevance tag and recency decay. Every
+ * component is in [0, 1]; higher is better.
+ */
+export function scoreObservation(textScore, relevance, createdAt, now) {
+    const ageDays = Math.max(0, (now - createdAt) / MS_PER_DAY);
+    const recency = Math.exp(-ageDays / RECENCY_DECAY_DAYS);
+    const relevanceWeight = RELEVANCE_WEIGHTS[relevance] ?? RELEVANCE_WEIGHTS.low;
+    return (textScore * WEIGHT_TEXT_MATCH +
+        relevanceWeight * WEIGHT_RELEVANCE +
+        recency * WEIGHT_RECENCY);
+}

package/dist/server/storage/preflight.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pre-flight: verify that the SQLite adapter loads and a writable DB can be
+ * opened.
+ *
+ * Called before binding the port so a broken native build fails loudly with
+ * a helpful hint instead of crashing later when the first WS connection
+ * arrives.
+ *
+ * Implementation note: we test by opening the *real* target path. Opening a
+ * tmpfile would only verify that the native module loads, not that the
+ * config dir is writable. Since `open()` already creates the file/dir
+ * idempotently, this is safe to call repeatedly.
+ */
+export interface PreflightResult {
+    ok: boolean;
+    /** Human-friendly error message ready to print. Set when ok=false. */
+    error?: string;
+}
+export declare function preflightSqlite(dbPath: string): PreflightResult;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/server/storage/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../../src/server/storage/preflight.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAmB/D"}

package/dist/server/storage/preflight.js

@@ -0,0 +1,22 @@
+import { SessionStore } from "../storage.js";
+import { getConfigDir } from "../../config.js";
+export function preflightSqlite(dbPath) {
+    try {
+        const store = new SessionStore(dbPath);
+        // Touch the schema check to make sure the DB is readable.
+        store.listTables();
+        store.close();
+        return { ok: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: `Failed to load the SQLite storage module (${msg}).\n` +
+                `  On Node >= 22.5 spectral uses the built-in node:sqlite module; on older\n` +
+                `  Node it falls back to better-sqlite3, which needs its native binary built.\n` +
+                `  Try: cd ${getConfigDir()} && npm rebuild better-sqlite3\n` +
+                `  Or reinstall: npm install -g @aexol/spectral`,
+        };
+    }
+}

package/dist/server/storage/project-binding.d.ts

@@ -0,0 +1,5 @@
+import { type StudioBinding } from "../../studio-binding.js";
+import type { WireProject } from "../wire.js";
+/** Augment a WireProject row with Studio binding fields when present. */
+export declare function applyBindingFields(project: WireProject, rowBinding?: StudioBinding | null): WireProject;
+//# sourceMappingURL=project-binding.d.ts.map