sentinelayer-cli 0.28.2 → 0.28.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.28.2",
+  "version": "0.28.4",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/session.js

@@ -145,6 +145,7 @@ const SESSION_SAY_LOCAL_ONLY_REASONS = new Set([
   "not_authenticated",
   "remote_sync_disabled_env",
 ]);
+const SESSION_READ_AUTO_VIEW_TIMEOUT_MS = 500;
 
 function isLocalOnlySessionSayReason(reason) {
   return SESSION_SAY_LOCAL_ONLY_REASONS.has(normalizeString(reason));
@@ -625,11 +626,76 @@ function sessionReadViewTarget(event = {}) {
   };
 }
 
-async function recordSessionReadViews(sessionId, events = [], {
+function normalizeAutoViewTimeoutMs(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return SESSION_READ_AUTO_VIEW_TIMEOUT_MS;
+  }
+  return Math.max(50, Math.min(5_000, Math.floor(parsed)));
+}
+
+async function writeSessionReadViews(sessionId, writeTargets = [], {
+  targetPath,
+  agentId,
+  timeoutMs = SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
+} = {}) {
+  if (!Array.isArray(writeTargets) || writeTargets.length === 0) {
+    return;
+  }
+  const totalTimeoutMs = normalizeAutoViewTimeoutMs(timeoutMs);
+  const controller = new AbortController();
+  const startedAt = Date.now();
+  const timeoutHandle = setTimeout(() => {
+    try {
+      controller.abort();
+    } catch {
+      // ignore
+    }
+  }, totalTimeoutMs);
+  if (typeof timeoutHandle.unref === "function") {
+    timeoutHandle.unref();
+  }
+
+  try {
+    for (const target of writeTargets) {
+      if (controller.signal.aborted) {
+        break;
+      }
+      const elapsedMs = Math.max(0, Date.now() - startedAt);
+      const remainingMs = Math.max(1, totalTimeoutMs - elapsedMs);
+      const result = await createSessionMessageAction(sessionId, {
+        actionType: "view",
+        targetPath,
+        targetSequenceId: target.targetSequenceId,
+        targetCursor: target.targetCursor,
+        metadata: {
+          source: "cli_read",
+          agentId,
+        },
+        idempotencyKey: defaultActionIdempotencyKey({
+          actionType: "view",
+          targetSequenceId: target.targetSequenceId,
+          targetCursor: target.targetCursor,
+          agentId,
+        }),
+        timeoutMs: remainingMs,
+        signal: controller.signal,
+      });
+      if (!result?.ok) {
+        break;
+      }
+    }
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+
+function recordSessionReadViews(sessionId, events = [], {
   targetPath,
   agentId,
   enabled = false,
   maxTargets = 50,
+  timeoutMs = SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
 } = {}) {
   const maxAutoViewTargets = Math.max(0, Math.min(200, Number(maxTargets) || 0));
   const summary = {
@@ -641,6 +707,8 @@ async function recordSessionReadViews(sessionId, events = [], {
     duplicates: 0,
     failed: 0,
     skipped: 0,
+    queued: 0,
+    background: false,
     reason: "",
   };
   if (!summary.enabled) {
@@ -662,42 +730,31 @@ async function recordSessionReadViews(sessionId, events = [], {
 
   const writeTargets = maxAutoViewTargets > 0 ? targets.slice(-maxAutoViewTargets) : [];
   summary.skipped = Math.max(0, targets.length - writeTargets.length);
+  summary.queued = writeTargets.length;
   if (summary.skipped > 0) {
     summary.reason = "target_cap_reached";
   }
 
-  for (const target of writeTargets) {
-    const result = await createSessionMessageAction(sessionId, {
-      actionType: "view",
-      targetPath,
-      targetSequenceId: target.targetSequenceId,
-      targetCursor: target.targetCursor,
-      metadata: {
-        source: "cli_read",
-        agentId: summary.agentId,
-      },
-      idempotencyKey: defaultActionIdempotencyKey({
-        actionType: "view",
-        targetSequenceId: target.targetSequenceId,
-        targetCursor: target.targetCursor,
-        agentId: summary.agentId,
-      }),
-      timeoutMs: 15_000,
-    });
-    summary.attempted += 1;
-    if (result?.ok && result.action) {
-      summary.recorded += 1;
-      if (result.duplicate) {
-        summary.duplicates += 1;
-      }
-      continue;
+  if (writeTargets.length === 0) {
+    if (!summary.reason) {
+      summary.reason = "no_targets";
     }
-    summary.failed += 1;
-    summary.reason = normalizeString(result?.reason) || "view_write_failed";
-    summary.skipped = Math.max(0, targets.length - summary.attempted);
-    break;
+    return summary;
+  }
+
+  summary.background = true;
+  if (!summary.reason) {
+    summary.reason = "queued_best_effort";
   }
 
+  void writeSessionReadViews(sessionId, writeTargets, {
+    targetPath,
+    agentId: summary.agentId,
+    timeoutMs,
+  }).catch(() => {
+    // Best-effort view receipts must never affect transcript rendering.
+  });
+
   return summary;
 }
 
@@ -4652,11 +4709,12 @@ export function registerSessionCommand(program) {
           : displayEvents.filter((event) => !isSessionControlEvent(event));
         const hiddenControlEventCount = displayEvents.length - transcriptEvents.length;
         const events = mergeSessionActionEvents(transcriptEvents, actionEvents).slice(-tail);
-        const autoView = await recordSessionReadViews(normalizedSessionId, events, {
+        const autoView = recordSessionReadViews(normalizedSessionId, events, {
           targetPath,
           agentId: readAgentId,
           enabled: Boolean(options.remote && options.view !== false),
           maxTargets: process.env.SENTINELAYER_SESSION_READ_VIEW_MAX_TARGETS || 50,
+          timeoutMs: process.env.SENTINELAYER_SESSION_READ_VIEW_TIMEOUT_MS || SESSION_READ_AUTO_VIEW_TIMEOUT_MS,
         });
         const remoteVerified = Boolean(
           options.remote &&

package/src/session/listener.js

@@ -311,6 +311,7 @@ export async function listenSessionEvents({
     const latest = await _pollLatest(normalizedSessionId, {
       targetPath,
       limit: 1,
+      forceCircuitProbe: true,
     });
     if (!latest?.ok) {
       throw new Error(`Unable to start listener from the latest event (${latest?.reason || "unknown"}).`);

package/src/session/sync.js

@@ -172,17 +172,6 @@ function resolveGrantRole(rawRole) {
   return AUTO_GRANT_DEFAULT_ROLE;
 }
 
-async function readResponseJsonSafely(response) {
-  if (!response || typeof response.json !== "function") {
-    return null;
-  }
-  try {
-    return await response.json();
-  } catch {
-    return null;
-  }
-}
-
 function isIdentityForgeryBody(body) {
   if (!body || typeof body !== "object") return false;
   const error = body.error;
@@ -412,6 +401,184 @@ function enforceRollingLimit(windowByKey, key, {
   };
 }
 
+function makeSyncTimeoutError(reason) {
+  const error = new Error(normalizeString(reason) || "request_timeout");
+  error.name = "AbortError";
+  error.code = "SYNC_REQUEST_TIMEOUT";
+  return error;
+}
+
+function combineAbortSignals(signals = []) {
+  const activeSignals = signals.filter((signal) => signal && typeof signal === "object");
+  if (activeSignals.length === 0) return undefined;
+  if (activeSignals.length === 1) return activeSignals[0];
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.any === "function") {
+    return AbortSignal.any(activeSignals);
+  }
+
+  const controller = new AbortController();
+  const abort = () => {
+    try {
+      controller.abort();
+    } catch {
+      // ignore
+    }
+    for (const signal of activeSignals) {
+      try {
+        signal.removeEventListener("abort", abort);
+      } catch {
+        // ignore
+      }
+    }
+  };
+  for (const signal of activeSignals) {
+    if (signal.aborted) {
+      abort();
+      break;
+    }
+    try {
+      signal.addEventListener("abort", abort, { once: true });
+    } catch {
+      // ignore
+    }
+  }
+  return controller.signal;
+}
+
+function abortRequestController(controller, reason) {
+  if (!controller || controller.signal?.aborted) return;
+  try {
+    controller.abort(makeSyncTimeoutError(reason));
+  } catch {
+    try {
+      controller.abort();
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function cancelResponseBody(response) {
+  try {
+    if (response?.body && typeof response.body.cancel === "function") {
+      void response.body.cancel();
+    }
+  } catch {
+    // Best-effort socket/body cleanup only.
+  }
+}
+
+function isSyncTimeoutError(error) {
+  return error?.code === "SYNC_REQUEST_TIMEOUT";
+}
+
+function withTimeout(promise, timeoutMs, { reason = "request_timeout", onTimeout = null } = {}) {
+  const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timeoutHandle = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try {
+        onTimeout?.();
+      } catch {
+        // ignore
+      }
+      reject(makeSyncTimeoutError(reason));
+    }, resolvedTimeoutMs);
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutHandle);
+      fn(value);
+    };
+
+    Promise.resolve(promise).then(
+      (value) => finish(resolve, value),
+      (error) => finish(reject, error),
+    );
+  });
+}
+
+async function readResponseJsonWithTimeout(
+  response,
+  timeoutMs,
+  {
+    timeoutReason = "response_body_timeout",
+    onTimeout = null,
+    fallback = undefined,
+  } = {},
+) {
+  if (!response || typeof response.json !== "function") {
+    return fallback;
+  }
+  try {
+    return await withTimeout(response.json(), timeoutMs, {
+      reason: timeoutReason,
+      onTimeout: () => {
+        try {
+          onTimeout?.();
+        } finally {
+          cancelResponseBody(response);
+        }
+      },
+    });
+  } catch (error) {
+    if (isSyncTimeoutError(error)) {
+      throw error;
+    }
+    if (fallback !== undefined) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function readResponseJsonSafely(response, timeoutMs = DEFAULT_SYNC_TIMEOUT_MS) {
+  try {
+    return await readResponseJsonWithTimeout(response, timeoutMs, { fallback: null });
+  } catch {
+    return null;
+  }
+}
+
+async function fetchJsonWithFullTimeout(
+  url,
+  options,
+  timeoutMs,
+  fetchImpl = fetchWithTimeout,
+  { readErrorBody = false } = {},
+) {
+  const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
+  const controller = new AbortController();
+  const startedAtMs = Date.now();
+  let response = null;
+  const requestOptions = {
+    ...options,
+    signal: combineAbortSignals([options?.signal, controller.signal]),
+  };
+
+  response = await withTimeout(
+    fetchImpl(url, requestOptions, resolvedTimeoutMs),
+    resolvedTimeoutMs,
+    {
+      reason: "request_timeout",
+      onTimeout: () => abortRequestController(controller, "request_timeout"),
+    },
+  );
+
+  let payload = {};
+  if (response?.ok || readErrorBody) {
+    const elapsedMs = Math.max(0, Date.now() - startedAtMs);
+    const remainingMs = Math.max(1, resolvedTimeoutMs - elapsedMs);
+    payload = await readResponseJsonWithTimeout(response, remainingMs, {
+      fallback: {},
+      onTimeout: () => abortRequestController(controller, "response_body_timeout"),
+    });
+  }
+  return { response, payload };
+}
+
 async function fetchWithTimeout(url, options, timeoutMs) {
   const controller = new AbortController();
   const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
@@ -421,7 +588,7 @@ async function fetchWithTimeout(url, options, timeoutMs) {
   try {
     return await fetch(url, {
       ...options,
-      signal: controller.signal,
+      signal: combineAbortSignals([options?.signal, controller.signal]),
     });
   } finally {
     clearTimeout(timeoutHandle);
@@ -1008,7 +1175,7 @@ export async function pollHumanMessages(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/human-messages?${query.toString()}`;
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
@@ -1016,7 +1183,8 @@ export async function pollHumanMessages(
           Authorization: `Bearer ${session.token}`,
         },
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
@@ -1027,7 +1195,6 @@ export async function pollHumanMessages(
         cursor: normalizedSince || null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(inboundCircuit);
 
     const items = normalizeHumanMessageItems(payload);
@@ -1171,13 +1338,14 @@ export async function pollSessionEvents(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events?${query.toString()}`;
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
         headers: { Authorization: `Bearer ${session.token}` },
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
@@ -1188,7 +1356,6 @@ export async function pollSessionEvents(
         cursor: normalizedSince || null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(inboundCircuit);
 
     const items = Array.isArray(payload?.events) ? payload.events : [];
@@ -1491,13 +1658,14 @@ export async function pollSessionEventsBefore(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events/before?${query.toString()}`;
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
         headers: { Authorization: `Bearer ${session.token}` },
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
@@ -1509,7 +1677,6 @@ export async function pollSessionEventsBefore(
         beforeSequence: Number.isFinite(normalizedBeforeSequence) ? normalizedBeforeSequence : null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(inboundCircuit);
 
     const events = chronologicalSessionEvents(payload?.events || []);
@@ -1600,13 +1767,14 @@ export async function listSessionMessageActions(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/actions?${query.toString()}`;
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
         headers: { Authorization: `Bearer ${session.token}` },
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
@@ -1618,7 +1786,6 @@ export async function listSessionMessageActions(
         projection: null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(inboundCircuit);
     const actions = Array.isArray(payload?.actions) ? payload.actions : [];
     return {
@@ -1772,6 +1939,7 @@ export async function createSessionMessageAction(
     metadata = {},
     idempotencyKey = "",
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    signal = undefined,
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetchWithTimeout,
     nowMs = Date.now,
@@ -1833,7 +2001,7 @@ export async function createSessionMessageAction(
   }
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "POST",
@@ -1842,8 +2010,10 @@ export async function createSessionMessageAction(
           Authorization: `Bearer ${session.token}`,
         },
         body: JSON.stringify(body),
+        signal,
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(outboundCircuit, normalizedNowMs);
@@ -1853,7 +2023,6 @@ export async function createSessionMessageAction(
         action: null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(outboundCircuit);
     return {
       ok: Boolean(payload?.ok ?? true),
@@ -1955,13 +2124,14 @@ export async function searchSessionEvents(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events/search?${queryParams.toString()}`;
 
   try {
-    const response = await fetchImpl(
+    const { response, payload } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
         headers: { Authorization: `Bearer ${session.token}` },
       },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      fetchImpl,
     );
     if (!response || !response.ok) {
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
@@ -1975,7 +2145,6 @@ export async function searchSessionEvents(
         nextBeforeSequence: null,
       };
     }
-    const payload = await response.json().catch(() => ({}));
     recordCircuitSuccess(inboundCircuit);
     const results = Array.isArray(payload?.results) ? payload.results : [];
     return {
@@ -2081,15 +2250,17 @@ export async function listSessionsFromApi({
     const endpoint = `${apiBaseUrl}/api/v1/sessions?${query.toString()}`;
 
     let response;
+    let payload;
     try {
-      response = await fetchImpl(
+      ({ response, payload } = await fetchJsonWithFullTimeout(
         endpoint,
         {
           method: "GET",
           headers: { Authorization: `Bearer ${session.token}` },
         },
         normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
-      );
+        fetchImpl,
+      ));
     } catch (err) {
       return {
         ok: false,
@@ -2114,7 +2285,6 @@ export async function listSessionsFromApi({
         warnings: [],
       };
     }
-    const payload = await response.json().catch(() => ({}));
     const pageSessions = Array.isArray(payload?.sessions) ? payload.sessions : [];
     for (const item of pageSessions) {
       const sessionId = normalizeString(item?.sessionId || item?.id);
@@ -2200,15 +2370,17 @@ export async function fetchSessionFromApi(
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
 
   let response;
+  let body;
   try {
-    response = await fetchImpl(
+    ({ response, payload: body } = await fetchJsonWithFullTimeout(
       endpoint,
       {
         method: "GET",
         headers: { Authorization: `Bearer ${session.token}` },
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
-    );
+      fetchImpl,
+    ));
   } catch (err) {
     return {
       ok: false,
@@ -2220,7 +2392,6 @@ export async function fetchSessionFromApi(
     return { ok: false, reason: "no_response", session: null };
   }
   if (response.ok) {
-    const body = await response.json().catch(() => ({}));
     const sessionPayload = body && body.session && typeof body.session === "object"
       ? body.session
       : body && typeof body === "object"