sentinelayer-cli 0.39.1 → 0.40.0

package/src/session/checkpoints.js

@@ -3,6 +3,7 @@ import process from "node:process";
 
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
+import { pollSessionEventsBefore } from "./sync.js";
 
 const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
 const DEFAULT_CHECKPOINT_LIMIT = 100;
@@ -11,6 +12,10 @@ const DEFAULT_MIN_EVENTS = 20;
 const DEFAULT_MAX_EVENTS = 80;
 const DEFAULT_BATCH_MAX_CHECKPOINTS = 5;
 const MAX_BATCH_MAX_CHECKPOINTS = 50;
+const DEFAULT_RESTORE_CONTEXT_EVENTS = 3;
+const DEFAULT_RESTORE_MAX_EVENTS = 120;
+const MAX_RESTORE_CONTEXT_EVENTS = 50;
+const MAX_RESTORE_EVENTS = 200;
 const DEFAULT_CREATED_BY_AGENT_ID = "senti";
 
 function normalizeString(value) {
@@ -33,6 +38,17 @@ function parsePositiveInteger(value, field, fallbackValue = null) {
   return Math.floor(parsed);
 }
 
+function parseNonNegativeInteger(value, field, fallbackValue = 0) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    return Math.max(0, Math.floor(Number(fallbackValue) || 0));
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    throw new Error(`${field} must be a non-negative integer.`);
+  }
+  return Math.floor(parsed);
+}
+
 function normalizeLimit(value) {
   const parsed = parsePositiveInteger(value, "limit", DEFAULT_CHECKPOINT_LIMIT);
   return Math.max(1, Math.min(MAX_CHECKPOINT_LIMIT, parsed));
@@ -47,6 +63,16 @@ function normalizeBatchMaxCheckpoints(value) {
   return Math.max(1, Math.min(MAX_BATCH_MAX_CHECKPOINTS, parsed));
 }
 
+function normalizeRestoreMaxEvents(value) {
+  const parsed = parsePositiveInteger(value, "max-events", DEFAULT_RESTORE_MAX_EVENTS);
+  return Math.max(1, Math.min(MAX_RESTORE_EVENTS, parsed));
+}
+
+function normalizeRestoreContextEvents(value) {
+  const parsed = parseNonNegativeInteger(value, "context-events", DEFAULT_RESTORE_CONTEXT_EVENTS);
+  return Math.max(0, Math.min(MAX_RESTORE_CONTEXT_EVENTS, parsed));
+}
+
 function stableHash(value) {
   return crypto
     .createHash("sha256")
@@ -148,6 +174,20 @@ function normalizeTokenRange({ tokenStart, tokenEnd } = {}) {
   return { start, end };
 }
 
+function checkpointIdOf(checkpoint = {}) {
+  return normalizeString(checkpoint.checkpointId || checkpoint.checkpoint_id);
+}
+
+function checkpointSequenceValue(checkpoint = {}, camelKey, snakeKey) {
+  const parsed = Number(checkpoint[camelKey] ?? checkpoint[snakeKey]);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+
+function eventSequenceValue(event = {}) {
+  const parsed = Number(event.sequenceId ?? event.sequence_id ?? event.sequence);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0;
+}
+
 export function buildManualCheckpointPayload(sessionId, {
   checkpointId = "",
   startSequence,
@@ -235,6 +275,99 @@ export function buildGenerateCheckpointPayload(sessionId, {
   };
 }
 
+export function findCheckpointById(checkpoints = [], checkpointId = "") {
+  const normalizedCheckpointId = normalizeString(checkpointId);
+  if (!normalizedCheckpointId) return null;
+  return Array.isArray(checkpoints)
+    ? checkpoints.find((checkpoint) => checkpointIdOf(checkpoint) === normalizedCheckpointId) || null
+    : null;
+}
+
+export function buildCheckpointRestoreWindow(checkpoint = {}, {
+  contextEvents = DEFAULT_RESTORE_CONTEXT_EVENTS,
+  maxEvents = DEFAULT_RESTORE_MAX_EVENTS,
+} = {}) {
+  const startSequence = checkpointSequenceValue(checkpoint, "startSequence", "start_sequence");
+  const endSequence = checkpointSequenceValue(checkpoint, "endSequence", "end_sequence");
+  if (startSequence <= 0) {
+    throw new Error("checkpoint startSequence is required for restore.");
+  }
+  if (endSequence <= 0) {
+    throw new Error("checkpoint endSequence is required for restore.");
+  }
+  if (startSequence > endSequence) {
+    throw new Error("checkpoint startSequence must be less than or equal to endSequence.");
+  }
+  const normalizedContext = normalizeRestoreContextEvents(contextEvents);
+  const normalizedMaxEvents = normalizeRestoreMaxEvents(maxEvents);
+  const sourceEventCountExpected = endSequence - startSequence + 1;
+  const requestedEventCount = sourceEventCountExpected + normalizedContext * 2;
+  const limit = Math.min(normalizedMaxEvents, requestedEventCount, MAX_RESTORE_EVENTS);
+  return {
+    checkpointId: checkpointIdOf(checkpoint) || null,
+    startSequence,
+    endSequence,
+    contextEvents: normalizedContext,
+    maxEvents: normalizedMaxEvents,
+    limit,
+    beforeSequence: endSequence + normalizedContext + 1,
+    lowerBoundSequence: Math.max(1, startSequence - normalizedContext),
+    sourceEventCountExpected,
+    truncatedByLimit: limit < requestedEventCount,
+  };
+}
+
+export function classifyCheckpointRestoreEvents(events = [], window = {}) {
+  const normalizedEvents = Array.isArray(events) ? events : [];
+  const startSequence = Number(window.startSequence || 0);
+  const endSequence = Number(window.endSequence || 0);
+  const sourceEventCountExpected = Number(window.sourceEventCountExpected || 0);
+  const beforeContextEvents = [];
+  const sourceEvents = [];
+  const afterContextEvents = [];
+  const sourceSequenceIds = new Set();
+
+  for (const event of normalizedEvents) {
+    const sequence = eventSequenceValue(event);
+    if (sequence <= 0) continue;
+    if (sequence < startSequence) {
+      beforeContextEvents.push(event);
+    } else if (sequence > endSequence) {
+      afterContextEvents.push(event);
+    } else {
+      sourceEvents.push(event);
+      sourceSequenceIds.add(sequence);
+    }
+  }
+
+  const missingStart = startSequence > 0 && !sourceSequenceIds.has(startSequence);
+  const missingEnd = endSequence > 0 && !sourceSequenceIds.has(endSequence);
+  const missingSourceEvents = Math.max(0, sourceEventCountExpected - sourceSequenceIds.size);
+  return {
+    events: normalizedEvents,
+    beforeContextEvents,
+    sourceEvents,
+    afterContextEvents,
+    eventCount: normalizedEvents.length,
+    beforeContextCount: beforeContextEvents.length,
+    sourceEventCount: sourceEvents.length,
+    afterContextCount: afterContextEvents.length,
+    missingStart,
+    missingEnd,
+    missingSourceEvents,
+    completeSourceRange:
+      sourceEventCountExpected > 0 &&
+      !missingStart &&
+      !missingEnd &&
+      missingSourceEvents === 0,
+    partial:
+      Boolean(window.truncatedByLimit) ||
+      missingStart ||
+      missingEnd ||
+      missingSourceEvents > 0,
+  };
+}
+
 export function normalizeCheckpointGenerationResult(payload = {}) {
   const source = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
   const checkpoint =
@@ -308,6 +441,63 @@ export async function listSessionCheckpoints(sessionId, {
   };
 }
 
+export async function showSessionCheckpoint(sessionId, checkpointId, {
+  targetPath = process.cwd(),
+  contextEvents = DEFAULT_RESTORE_CONTEXT_EVENTS,
+  maxEvents = DEFAULT_RESTORE_MAX_EVENTS,
+  resolveAuthSession = resolveActiveAuthSession,
+  request = requestJson,
+  fetchEventsBefore = pollSessionEventsBefore,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedCheckpointId = normalizeString(checkpointId);
+  if (!normalizedCheckpointId) {
+    throw new Error("checkpoint id is required.");
+  }
+
+  const listed = await listSessionCheckpoints(normalizedSessionId, {
+    targetPath,
+    limit: MAX_CHECKPOINT_LIMIT,
+    resolveAuthSession,
+    request,
+  });
+  const checkpoint = findCheckpointById(listed.checkpoints, normalizedCheckpointId);
+  if (!checkpoint) {
+    throw new Error(`Checkpoint '${normalizedCheckpointId}' was not found in session ${normalizedSessionId}.`);
+  }
+  const restoreWindow = buildCheckpointRestoreWindow(checkpoint, {
+    contextEvents,
+    maxEvents,
+  });
+  const remote = await fetchEventsBefore(normalizedSessionId, {
+    targetPath,
+    beforeSequence: restoreWindow.beforeSequence,
+    limit: restoreWindow.limit,
+    forceCircuitProbe: true,
+    resolveAuthSession,
+  });
+  const classified = classifyCheckpointRestoreEvents(remote?.events || [], restoreWindow);
+  return {
+    ok: Boolean(remote?.ok),
+    reason: normalizeString(remote?.reason),
+    sessionId: normalizedSessionId,
+    checkpointId: normalizedCheckpointId,
+    apiUrl: listed.apiUrl,
+    checkpoint,
+    window: {
+      ...restoreWindow,
+      ...classified,
+      remoteOk: Boolean(remote?.ok),
+      remoteReason: normalizeString(remote?.reason),
+      remoteBeforeSequence: remote?.beforeSequence || null,
+      remoteCursor: remote?.cursor || null,
+    },
+  };
+}
+
 export async function createSessionCheckpoint(sessionId, options = {}) {
   const normalizedSessionId = normalizeString(sessionId);
   const {
@@ -446,5 +636,9 @@ export {
   DEFAULT_BATCH_MAX_CHECKPOINTS,
   DEFAULT_MAX_EVENTS,
   DEFAULT_MIN_EVENTS,
+  DEFAULT_RESTORE_CONTEXT_EVENTS,
+  DEFAULT_RESTORE_MAX_EVENTS,
   MAX_BATCH_MAX_CHECKPOINTS,
+  MAX_RESTORE_CONTEXT_EVENTS,
+  MAX_RESTORE_EVENTS,
 };

package/src/session/pricing-ledger.js

@@ -296,6 +296,7 @@ export function buildEstimatedMessageLedgerEntry(
     billingTier = "estimated",
     includeHumanMessages = false,
     action = "estimated_agent_message",
+    estimatedMessageTokenBackend = null,
   } = {},
 ) {
   const kind = n(event?.event || event?.type);
@@ -322,6 +323,7 @@ export function buildEstimatedMessageLedgerEntry(
   const outputTokens = estimateTokens(text, {
     model,
     provider: n(agent.provider || payload.provider),
+    backend: estimatedMessageTokenBackend,
   });
   if (outputTokens <= 0) return null;
 

package/src/session/recap.js

@@ -21,6 +21,7 @@ const DEFAULT_RECAP_ACTIVITY_THRESHOLD = 5;
 const DEFAULT_TASK_SUMMARY_LIMIT = 3;
 const DEFAULT_WORK_PLAN_SUMMARY_LIMIT = 5;
 const DEFAULT_ACTIVITY_SNIPPET_MAX_CHARS = 120;
+const RECAP_ESTIMATED_USAGE_CHARS_PER_TOKEN = 4;
 const MAX_WORK_PLAN_BYTES = 128_000;
 const WORK_PLAN_RELATIVE_PATH = "tasks/todo.md";
 const ACTIVE_WORK_PLAN_FILE_PATTERN = /^reconciled-fix-plan-\d{4}-\d{2}-\d{2}\.md$/;
@@ -1027,8 +1028,19 @@ function roundCurrency(value) {
   return Math.round(normalized * 1_000_000) / 1_000_000;
 }
 
+function estimateRecapMessageTokens(text) {
+  const normalized = normalizeString(text);
+  if (!normalized) {
+    return 0;
+  }
+  return Math.max(1, Math.ceil(normalized.length / RECAP_ESTIMATED_USAGE_CHARS_PER_TOKEN));
+}
+
 function normalizeUsageSummary(events = []) {
-  const aggregate = aggregateSessionUsage(events, { includeEstimatedMessages: true });
+  const aggregate = aggregateSessionUsage(events, {
+    includeEstimatedMessages: true,
+    estimatedMessageTokenBackend: estimateRecapMessageTokens,
+  });
   const totals = {
     totalTokens: Number(aggregate.totals.totalTokens || 0),
     inputTokens: Number(aggregate.totals.inputTokens || 0),