sidekick-shared 0.18.3 → 0.18.5

package/README.md

@@ -26,6 +26,7 @@ npm install sidekick-shared
 | **Formatters** | Display helpers (`formatTokenCount()`, `formatDurationMs()`), tool summary, noise classification, session dump (text/markdown/JSON), event highlighting |
 | **Search** | Cross-session full-text search, advanced filtering (substring, fuzzy, regex, date) |
 | **Aggregation** | Event aggregation, frequency tracking, activity heatmaps, pattern extraction |
+| **Session Context** | Provider-neutral context evidence snapshots (`buildSessionContextSnapshot()`, `calculateSessionContextPressure()`, `createSessionContextProjector()`, `readSessionContextSnapshot()`): layered evidence sources, low/medium/high context pressure, and observed capabilities (tools, MCP servers, permission mode, rate limits) |
 | **Report** | Self-contained HTML session report generation |
 | **Credentials** | Claude Max OAuth credential reading from `~/.claude/.credentials.json` |
 | **Quota** | Claude Max subscription quota fetching (5-hour and 7-day windows) and Codex rate-limit extraction from event streams |
@@ -180,6 +181,26 @@ const tools = extractToolCalls(event);           // ToolCall[]    — assistant
 const toolFromEvent = extractToolCall(event);    // ToolCall | null — top-level `tool_use` events
 ```
 
+### Project session context evidence
+
+Build a provider-neutral snapshot of what an assistant has "seen" in a session — layered evidence sources, context pressure, and observed capabilities. Read it through any session provider, or build it directly from a canonical `SessionEvent[]`.
+
+```typescript
+import { detectProvider, readSessionContextSnapshot } from 'sidekick-shared';
+
+const provider = await detectProvider('/path/to/project');
+if (provider) {
+  const snapshot = readSessionContextSnapshot(provider, '/path/to/session.jsonl');
+
+  console.log(snapshot.pressure);          // 'low' | 'medium' | 'high'
+  console.log(snapshot.contextTokens, '/', snapshot.contextWindow);
+  console.log(snapshot.capabilities.tools, snapshot.capabilities.mcpServers);
+  console.log(snapshot.sources.length, 'evidence sources');
+}
+```
+
+Use `createSessionContextProjector()` for incremental updates as new events stream in, or `calculateSessionContextPressure(contextTokens, contextWindow)` for the pressure band alone.
+
 ### Format shared dashboard values
 
 ```typescript

package/dist/aggregation/EventAggregator.js

@@ -157,25 +157,29 @@ class EventAggregator {
         if (event.message.model) {
             this.currentModel = event.message.model;
         }
-        // 3. Skip synthetic token-count events for messageCount
+        // 3. Skip system/audit events and synthetic token-count events for messageCount
         const msgId = event.message.id ?? '';
-        if (!msgId.startsWith('token-count-')) {
+        if (event.type !== 'system' && !msgId.startsWith('token-count-')) {
             this.messageCount++;
         }
         // 4. Latency tracking
-        this.processLatency(event);
+        if (event.type !== 'system') {
+            this.processLatency(event);
+        }
         // 5. Token accumulation
         if (event.message.usage) {
             this.accumulateUsage(event.message.usage, event.timestamp, event.message.model);
         }
-        // 6. Tool extraction from content blocks
-        this.extractToolsFromContent(event);
-        // 7. Task state
-        this.extractTaskStateFromEvent(event);
-        // 8. Subagent tracking
-        this.extractSubagentFromEvent(event);
-        // 9. Plan extraction — convert SessionEvent to a FollowEvent shape for PlanExtractor
-        this.extractPlanFromSessionEvent(event);
+        if (event.type !== 'system') {
+            // 6. Tool extraction from content blocks
+            this.extractToolsFromContent(event);
+            // 7. Task state
+            this.extractTaskStateFromEvent(event);
+            // 8. Subagent tracking
+            this.extractSubagentFromEvent(event);
+            // 9. Plan extraction — convert SessionEvent to a FollowEvent shape for PlanExtractor
+            this.extractPlanFromSessionEvent(event);
+        }
         // 10. Context attribution
         this.attributeContextFromEvent(event);
         // 11. Permission mode tracking
@@ -1447,6 +1451,12 @@ class EventAggregator {
                 this.contextAttribution.other += this.estimateTokens(text);
             }
         }
+        else if (event.type === 'system') {
+            const text = this.extractTextContent(event) || '';
+            if (text) {
+                this.contextAttribution.systemPrompt += this.estimateTokens(text);
+            }
+        }
     }
     // ═══════════════════════════════════════════════════════════════════════
     // Private: Context Attribution from FollowEvent
@@ -1591,6 +1601,11 @@ class EventAggregator {
                 description = 'Context compacted';
                 noiseLevel = 'system';
                 break;
+            case 'system':
+                tlType = 'session_start';
+                description = this.extractTextContent(event) ?? event.message.sourceLabel ?? 'System event';
+                noiseLevel = 'system';
+                break;
             default:
                 tlType = 'session_start';
                 description = 'Event';

package/dist/browser.d.ts

@@ -10,5 +10,7 @@
 export { getModelContextWindowSize, DEFAULT_CONTEXT_WINDOW } from './modelContext';
 export { formatDurationMs, formatTokenCount } from './formatting';
 export type { FormatDurationMsOptions, FormatTokenCountOptions } from './formatting';
+export { buildSessionContextSnapshot, calculateSessionContextPressure, createSessionContextProjector, } from './context/sessionContext';
+export type { BuildSessionContextSnapshotOptions, SessionContextCapabilities, SessionContextLayerBreakdown, SessionContextPressure, SessionContextProjector, SessionContextSnapshot, SessionContextSource, SessionContextSourceType, } from './context/sessionContext';
 export { parseModelId, getModelPricing, getModelInfo, calculateCost, calculateCostWithPricing, calculateCostWithProvenance, mergeCostSources, shortModelName, getModelDisplayInfo, compareModelIds, sortModelIds, formatCost, } from './modelInfo';
 export type { ModelPricing, CostTokenUsage, CostSource, CostProvenanceInput, CostWithProvenance, ModelProvider, ParsedModelId, ModelInfo, ModelDisplayInfo, } from './modelInfo';

package/dist/browser.js

@@ -9,13 +9,17 @@
  * For pricing hydration (LiteLLM catalog refresh), use `sidekick-shared/node`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.formatTokenCount = exports.formatDurationMs = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = void 0;
+exports.formatCost = exports.sortModelIds = exports.compareModelIds = exports.getModelDisplayInfo = exports.shortModelName = exports.mergeCostSources = exports.calculateCostWithProvenance = exports.calculateCostWithPricing = exports.calculateCost = exports.getModelInfo = exports.getModelPricing = exports.parseModelId = exports.createSessionContextProjector = exports.calculateSessionContextPressure = exports.buildSessionContextSnapshot = exports.formatTokenCount = exports.formatDurationMs = exports.DEFAULT_CONTEXT_WINDOW = exports.getModelContextWindowSize = void 0;
 var modelContext_1 = require("./modelContext");
 Object.defineProperty(exports, "getModelContextWindowSize", { enumerable: true, get: function () { return modelContext_1.getModelContextWindowSize; } });
 Object.defineProperty(exports, "DEFAULT_CONTEXT_WINDOW", { enumerable: true, get: function () { return modelContext_1.DEFAULT_CONTEXT_WINDOW; } });
 var formatting_1 = require("./formatting");
 Object.defineProperty(exports, "formatDurationMs", { enumerable: true, get: function () { return formatting_1.formatDurationMs; } });
 Object.defineProperty(exports, "formatTokenCount", { enumerable: true, get: function () { return formatting_1.formatTokenCount; } });
+var sessionContext_1 = require("./context/sessionContext");
+Object.defineProperty(exports, "buildSessionContextSnapshot", { enumerable: true, get: function () { return sessionContext_1.buildSessionContextSnapshot; } });
+Object.defineProperty(exports, "calculateSessionContextPressure", { enumerable: true, get: function () { return sessionContext_1.calculateSessionContextPressure; } });
+Object.defineProperty(exports, "createSessionContextProjector", { enumerable: true, get: function () { return sessionContext_1.createSessionContextProjector; } });
 var modelInfo_1 = require("./modelInfo");
 Object.defineProperty(exports, "parseModelId", { enumerable: true, get: function () { return modelInfo_1.parseModelId; } });
 Object.defineProperty(exports, "getModelPricing", { enumerable: true, get: function () { return modelInfo_1.getModelPricing; } });

package/dist/codexQuota.js

@@ -46,6 +46,36 @@ const codex_1 = require("./providers/codex");
 const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024;
 const DEFAULT_MAX_SESSION_FILES = 50;
 const CHATGPT_USAGE_URL = 'https://chatgpt.com/backend-api/wham/usage';
+function timestampMs(value, fallbackMs = 0) {
+    if (!value)
+        return fallbackMs;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : fallbackMs;
+}
+// Codex can report slightly different percentages for the same reset window
+// across recent sessions. Prefer newer reset windows, then the highest observed
+// same-window utilization so local fallbacks do not under-report quota usage.
+function isPreferredQuotaHit(candidate, current) {
+    if (!current)
+        return true;
+    const candidatePrimaryReset = timestampMs(candidate.quota.fiveHour.resetsAt);
+    const currentPrimaryReset = timestampMs(current.quota.fiveHour.resetsAt);
+    if (candidatePrimaryReset !== currentPrimaryReset)
+        return candidatePrimaryReset > currentPrimaryReset;
+    const candidateSecondaryReset = timestampMs(candidate.quota.sevenDay.resetsAt);
+    const currentSecondaryReset = timestampMs(current.quota.sevenDay.resetsAt);
+    if (candidateSecondaryReset !== currentSecondaryReset)
+        return candidateSecondaryReset > currentSecondaryReset;
+    const candidateUtilization = candidate.quota.fiveHour.utilization + candidate.quota.sevenDay.utilization;
+    const currentUtilization = current.quota.fiveHour.utilization + current.quota.sevenDay.utilization;
+    if (candidateUtilization !== currentUtilization)
+        return candidateUtilization > currentUtilization;
+    const candidateMs = timestampMs(candidate.quota.capturedAt, candidate.mtimeMs);
+    const currentMs = timestampMs(current.quota.capturedAt, current.mtimeMs);
+    if (candidateMs !== currentMs)
+        return candidateMs > currentMs;
+    return candidate.mtimeMs > current.mtimeMs;
+}
 function normalizePercent(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
@@ -175,14 +205,53 @@ function quotaFromCodexRateLimits(rateLimits, source = 'session', capturedAt = n
     };
 }
 function readLatestCodexQuotaFromRollouts(sessionPaths, options = {}) {
+    return readLatestCodexQuotaHitFromRollouts(sessionPaths, options)?.quota ?? null;
+}
+function readLatestCodexQuotaHitFromRollouts(sessionPaths, options = {}) {
     const maxSessionFiles = options.maxSessionFiles ?? DEFAULT_MAX_SESSION_FILES;
     const maxTailBytes = options.maxTailBytes ?? DEFAULT_TAIL_BYTES;
+    let latest = null;
     for (const sessionPath of sessionPaths.slice(0, maxSessionFiles)) {
         const hit = readLatestQuotaFromRollout(sessionPath, maxTailBytes, options.source ?? 'session');
-        if (hit)
-            return hit.quota;
+        if (hit && isPreferredQuotaHit(hit, latest)) {
+            latest = hit;
+        }
     }
-    return null;
+    return latest;
+}
+function dedupePaths(paths) {
+    const seen = new Set();
+    const unique = [];
+    for (const filePath of paths) {
+        if (seen.has(filePath))
+            continue;
+        seen.add(filePath);
+        unique.push(filePath);
+    }
+    return unique;
+}
+function sortPathsByMtimeDesc(paths) {
+    return [...paths].sort((a, b) => {
+        const aMtime = safeMtimeMs(a);
+        const bMtime = safeMtimeMs(b);
+        return bMtime - aMtime;
+    });
+}
+function safeMtimeMs(filePath) {
+    try {
+        return fs.statSync(filePath).mtime.getTime();
+    }
+    catch {
+        return 0;
+    }
+}
+function findAccountRolloutFiles(codexHome) {
+    const homes = codexHome ? [codexHome] : (0, codexProfiles_1.getCodexMonitoringHomes)();
+    const files = [];
+    for (const home of homes) {
+        files.push(...findRolloutFiles(path.join(home, 'sessions')));
+    }
+    return sortPathsByMtimeDesc(dedupePaths(files));
 }
 function resolveCodexQuotaFromLocalSources(options = {}) {
     const account = options.activeAccount !== undefined ? options.activeAccount : (0, codexProfiles_1.getActiveCodexAccount)();
@@ -196,20 +265,22 @@ function resolveCodexQuotaFromLocalSources(options = {}) {
         return new codex_1.CodexProvider();
     })();
     try {
-        const workspaceSessions = options.workspacePath ? provider.findAllSessions(options.workspacePath) : [];
-        const workspaceQuota = readLatestCodexQuotaFromRollouts(workspaceSessions, { maxTailBytes, maxSessionFiles });
-        if (workspaceQuota) {
-            if (account)
-                writeSnapshot('codex', account.id, workspaceQuota);
-            return enrichCodexQuota(workspaceQuota, account);
+        const candidates = [];
+        if (options.workspacePath) {
+            const workspaceSessions = provider.findAllSessions(options.workspacePath);
+            const workspaceHit = readLatestCodexQuotaHitFromRollouts(workspaceSessions, { maxTailBytes, maxSessionFiles });
+            if (workspaceHit)
+                candidates.push(workspaceHit);
         }
-        const codexHome = options.codexHome ?? (0, codexProfiles_1.resolveSidekickCodexHome)();
-        const accountSessions = findRolloutFiles(path.join(codexHome, 'sessions'));
-        const accountQuota = readLatestCodexQuotaFromRollouts(accountSessions, { maxTailBytes, maxSessionFiles });
-        if (accountQuota) {
+        const accountSessions = findAccountRolloutFiles(options.codexHome);
+        const accountHit = readLatestCodexQuotaHitFromRollouts(accountSessions, { maxTailBytes, maxSessionFiles });
+        if (accountHit)
+            candidates.push(accountHit);
+        const latestHit = candidates.reduce((latest, candidate) => isPreferredQuotaHit(candidate, latest) ? candidate : latest, null);
+        if (latestHit) {
             if (account)
-                writeSnapshot('codex', account.id, accountQuota);
-            return enrichCodexQuota(accountQuota, account);
+                writeSnapshot('codex', account.id, latestHit.quota);
+            return enrichCodexQuota(latestHit.quota, account);
         }
         const cached = account ? readSnapshot('codex', account.id) : null;
         if (cached) {
@@ -378,7 +449,7 @@ function readLatestQuotaFromRollout(sessionPath, maxTailBytes, source) {
                     continue;
                 const quota = quotaFromCodexRateLimits(parsed.payload.rate_limits, source, parsed.timestamp ?? new Date(stat.mtime).toISOString());
                 if (quota)
-                    return { quota, filePath: sessionPath };
+                    return { quota, filePath: sessionPath, mtimeMs: stat.mtime.getTime() };
             }
             catch {
                 // Ignore malformed or partial lines.

package/dist/context/sessionContext.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Provider-neutral session context evidence projection.
+ *
+ * Converts canonical SessionEvent streams into a compact manifest suitable for
+ * UI surfaces that need to explain what an assistant/provider has seen.
+ */
+import type { AggregatedMetrics } from '../aggregation/types';
+import type { ProviderId, SessionProviderBase } from '../providers/types';
+import type { CompactionEvent, ContextAttribution, PermissionMode, SessionEvent, TruncationEvent } from '../types/sessionEvent';
+export type SessionContextPressure = 'low' | 'medium' | 'high';
+export type SessionContextSourceType = 'system' | 'runtime' | 'rate_limit' | 'user_prompt' | 'assistant_response' | 'thinking' | 'tool_input' | 'tool_output' | 'summary' | 'error' | 'other';
+export interface SessionContextLayerBreakdown {
+    layer: string;
+    tokenEstimate: number;
+    sourceCount: number;
+}
+export interface SessionContextSource {
+    id: string;
+    providerId?: ProviderId;
+    sessionId?: string;
+    sessionPath?: string;
+    eventType: SessionEvent['type'];
+    timestamp: string;
+    layer: string;
+    sourceType: SessionContextSourceType;
+    title: string;
+    sourceRef?: string;
+    sourceFile?: string;
+    toolName?: string;
+    score?: number;
+    tokenEstimate: number;
+    snippet: string;
+    body?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface SessionContextCapabilities {
+    providerId?: ProviderId;
+    providerLabel?: string;
+    model?: string;
+    observedTools: string[];
+    mcpServers: string[];
+    permissionMode?: PermissionMode;
+    rateLimits?: SessionEvent['rateLimits'];
+}
+export interface SessionContextSnapshot {
+    schemaVersion: 1;
+    providerId?: ProviderId;
+    sessionId?: string;
+    sessionPath?: string;
+    model?: string;
+    contextWindow: number;
+    contextTokens: number;
+    pressure: SessionContextPressure;
+    pressureRatio: number;
+    layers: string[];
+    breakdown: SessionContextLayerBreakdown[];
+    sources: SessionContextSource[];
+    capabilities: SessionContextCapabilities;
+    attribution: ContextAttribution;
+    tokens: AggregatedMetrics['tokens'];
+    compactionCount: number;
+    compactionEvents: CompactionEvent[];
+    truncationCount: number;
+    truncationEvents: TruncationEvent[];
+}
+export interface BuildSessionContextSnapshotOptions {
+    providerId?: ProviderId;
+    providerLabel?: string;
+    sessionId?: string;
+    sessionPath?: string;
+    model?: string;
+    contextWindow?: number;
+    contextWindowForModel?: (modelId?: string) => number;
+    computeContextSize?: (usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheWriteTokens: number;
+        cacheReadTokens: number;
+        reasoningTokens?: number;
+    }) => number;
+    includeBodies?: boolean;
+    bodyMaxChars?: number;
+    snippetMaxChars?: number;
+    sourceLimit?: number;
+}
+export type ReadSessionContextSnapshotOptions = Omit<BuildSessionContextSnapshotOptions, 'providerId' | 'providerLabel' | 'sessionId' | 'sessionPath' | 'contextWindowForModel' | 'computeContextSize'>;
+export interface SessionContextProjector {
+    processEvent(event: SessionEvent): SessionContextSnapshot;
+    processEvents(events: readonly SessionEvent[]): SessionContextSnapshot;
+    getSnapshot(): SessionContextSnapshot;
+    reset(): void;
+}
+export declare function calculateSessionContextPressure(contextTokens: number, contextWindow: number): {
+    pressure: SessionContextPressure;
+    ratio: number;
+};
+export declare function buildSessionContextSnapshot(events: readonly SessionEvent[], options?: BuildSessionContextSnapshotOptions): SessionContextSnapshot;
+export declare function createSessionContextProjector(options?: BuildSessionContextSnapshotOptions): SessionContextProjector;
+export declare function readSessionContextSnapshot(provider: SessionProviderBase, sessionPath: string, options?: ReadSessionContextSnapshotOptions): SessionContextSnapshot;