sentinelayer-cli 0.9.0 → 0.9.3

package/src/session/sync.js

@@ -14,6 +14,7 @@ const SESSION_INGEST_LIMIT_PER_MINUTE = 500;
 const HUMAN_MESSAGE_LIMIT_PER_MINUTE = 10;
 const HUMAN_MESSAGE_MAX_LENGTH = 2_000;
 const HUMAN_MESSAGE_FETCH_LIMIT = 50;
+const SESSION_EVENT_FETCH_LIMIT = 200;
 
 // Audit §2.9: crash-recovery contract for in-memory circuit state.
 // Persist outbound/inbound circuit state to disk so a process restart
@@ -103,6 +104,96 @@ const inboundCircuit = {
 const sessionIngestWindowBySessionId = new Map();
 const humanRelayWindowBySessionId = new Map();
 
+// Per-process record of agent identities for which we have already issued an
+// auto-grant attempt against `POST /api/v1/sessions/agent-grants`. Server-side
+// agent-identity enforcement (PR #478) returns 403 IDENTITY_FORGERY when the
+// active user has not granted the `agent.id` carried on a session event. The
+// CLI auto-grants on the first 403 and retries the event POST exactly once,
+// but if the grant itself fails (e.g. 422 from a malformed agent_id), we MUST
+// NOT loop. This Set is the loop-breaker: insertion order is preserved (Set
+// semantics in V8) so an LRU-ish trim drops the oldest entries first when the
+// cap is exceeded. SessionId-agnostic by design — once a user grants
+// `agent.id="codex"`, the grant is global to their account.
+const AUTO_GRANT_ATTEMPT_CACHE_MAX = 50;
+const autoGrantAttemptedAgentIds = new Set();
+
+// Reserved agent_id values that the API treats specially — granting these
+// is either a no-op or rejected outright. Skip the auto-grant round-trip and
+// return the original 403 cleanly.
+const AUTO_GRANT_RESERVED_PREFIXES = ["human-"];
+const AUTO_GRANT_RESERVED_EXACT = new Set(["", "cli-user", "unknown"]);
+
+// API role enum (per PR #478 server contract). Anything not in this set
+// (notably the legacy `orchestrator` role we still emit locally) falls back
+// to `coder`. This is a forward-compat workaround pending an API enum
+// extension that adds `orchestrator`.
+const AUTO_GRANT_VALID_ROLES = new Set([
+  "auditor",
+  "coder",
+  "coordinator",
+  "observer",
+  "reviewer",
+]);
+const AUTO_GRANT_DEFAULT_ROLE = "coder";
+
+function rememberAutoGrantAttempt(agentId) {
+  if (!agentId) return;
+  if (autoGrantAttemptedAgentIds.has(agentId)) {
+    // Refresh insertion order so the most recently used entry survives
+    // LRU eviction when the cap is hit.
+    autoGrantAttemptedAgentIds.delete(agentId);
+    autoGrantAttemptedAgentIds.add(agentId);
+    return;
+  }
+  autoGrantAttemptedAgentIds.add(agentId);
+  while (autoGrantAttemptedAgentIds.size > AUTO_GRANT_ATTEMPT_CACHE_MAX) {
+    const oldest = autoGrantAttemptedAgentIds.values().next().value;
+    if (oldest === undefined) break;
+    autoGrantAttemptedAgentIds.delete(oldest);
+  }
+}
+
+function isReservedAgentIdForGrant(agentId) {
+  const id = normalizeString(agentId);
+  if (AUTO_GRANT_RESERVED_EXACT.has(id)) return true;
+  for (const prefix of AUTO_GRANT_RESERVED_PREFIXES) {
+    if (id.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+function resolveGrantRole(rawRole) {
+  const normalized = normalizeString(rawRole).toLowerCase();
+  if (AUTO_GRANT_VALID_ROLES.has(normalized)) {
+    return normalized;
+  }
+  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;
+  if (!error || typeof error !== "object") return false;
+  return normalizeString(error.code) === "IDENTITY_FORGERY";
+}
+
+// Test-only: clear the per-process auto-grant attempt cache so unit tests
+// exercising the loop-breaker don't bleed state across runs.
+export function __resetAutoGrantCacheForTests() {
+  autoGrantAttemptedAgentIds.clear();
+}
+
 const SECRET_LIKE_PATTERN =
   /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]+PRIVATE KEY-----|SENTINELAYER_TOKEN|AIDENID_API_KEY|NPM_TOKEN|xox[baprs]-[A-Za-z0-9-]+)/i;
 
@@ -130,6 +221,39 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function eventTimestampMs(event = {}) {
+  for (const key of ["ts", "timestamp", "createdAt", "at"]) {
+    const epoch = Date.parse(normalizeString(event?.[key]));
+    if (Number.isFinite(epoch)) {
+      return epoch;
+    }
+  }
+  return 0;
+}
+
+function eventSequenceNumber(event = {}) {
+  for (const key of ["sequenceId", "sequence_id", "sequence"]) {
+    const value = Number(event?.[key]);
+    if (Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return 0;
+}
+
+function chronologicalSessionEvents(events = []) {
+  return (Array.isArray(events) ? events : [])
+    .map((event, index) => ({ event, index }))
+    .sort((left, right) => {
+      const timeDiff = eventTimestampMs(left.event) - eventTimestampMs(right.event);
+      if (timeDiff !== 0) return timeDiff;
+      const sequenceDiff = eventSequenceNumber(left.event) - eventSequenceNumber(right.event);
+      if (sequenceDiff !== 0) return sequenceDiff;
+      return left.index - right.index;
+    })
+    .map((entry) => entry.event);
+}
+
 // Session-apiUrl allowlist. A session file is an untrusted input: if an
 // attacker can write to .sentinelayer/sessions/<id>/meta.json (or trick a user
 // into joining a crafted session), they can redirect every outbound fetch.
@@ -435,7 +559,11 @@ export async function syncSessionEventToApi(
     };
   }
 
-  if (event?.payload?.relayedFromApi) {
+  if (
+    event?.payload?.relayedFromApi ||
+    normalizeString(event?.cursor) ||
+    normalizeString(event?.sequenceId || event?.sequence_id)
+  ) {
     return { synced: false, reason: "relay_event_skip" };
   }
 
@@ -456,35 +584,125 @@ export async function syncSessionEventToApi(
 
   const apiBaseUrl = resolveApiBaseUrl(session);
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events`;
+  const requestBody = JSON.stringify({
+    event,
+    source: "cli",
+  });
+  const requestInit = {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${session.token}`,
+    },
+    body: requestBody,
+  };
+  const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
 
   try {
-    const response = await fetchImpl(
-      endpoint,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
-        },
-        body: JSON.stringify({
-          event,
-          source: "cli",
-        }),
-      },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
-    );
+    const response = await fetchImpl(endpoint, requestInit, resolvedTimeoutMs);
 
-    if (!response || !response.ok) {
-      recordCircuitFailure(outboundCircuit, normalizedNowMs);
+    if (response && response.ok) {
+      recordCircuitSuccess(outboundCircuit);
       return {
-        synced: false,
-        reason: `api_${response ? response.status : "no_response"}`,
+        synced: true,
+        status: response.status,
       };
     }
-    recordCircuitSuccess(outboundCircuit);
+
+    // Handle PR #478 IDENTITY_FORGERY: server now requires the active user to
+    // have explicitly granted any `agent.id` posted to /events. Without this
+    // auto-grant, every CLI-driven agent post returns 403 and the user sees
+    // their agents "talking" locally while the API has zero record. We attempt
+    // the grant once per agentId per process, then retry the event POST once.
+    if (response && response.status === 403) {
+      const body = await readResponseJsonSafely(response);
+      if (isIdentityForgeryBody(body)) {
+        const agentId = normalizeString(event?.agent?.id);
+        if (!agentId || isReservedAgentIdForGrant(agentId)) {
+          // Reserved or empty — server enforcement is intentional, no grant
+          // attempt is meaningful. Treat as a normal 403 failure.
+          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          return { synced: false, reason: "api_403" };
+        }
+        if (autoGrantAttemptedAgentIds.has(agentId)) {
+          // We already tried to grant this identity in a prior event in this
+          // process and either it succeeded but the server still says no, or
+          // the grant failed. Either way, don't loop — surface the 403.
+          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          return { synced: false, reason: "api_403" };
+        }
+        rememberAutoGrantAttempt(agentId);
+
+        const grantRole = resolveGrantRole(event?.agent?.role);
+        const grantEndpoint = `${apiBaseUrl}/api/v1/sessions/agent-grants`;
+        let grantResponse = null;
+        try {
+          grantResponse = await fetchImpl(
+            grantEndpoint,
+            {
+              method: "POST",
+              headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${session.token}`,
+              },
+              body: JSON.stringify({
+                agent_id: agentId,
+                role: grantRole,
+              }),
+            },
+            resolvedTimeoutMs
+          );
+        } catch (grantError) {
+          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          return {
+            synced: false,
+            reason: normalizeString(grantError?.message) || "grant_failed",
+          };
+        }
+
+        const grantStatus = grantResponse ? grantResponse.status : 0;
+        const grantOk = Boolean(grantResponse && grantResponse.ok);
+        // Treat 409 (already granted) as success — idempotent on the server.
+        const grantIdempotent = grantStatus === 409;
+        if (!grantOk && !grantIdempotent) {
+          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          return {
+            synced: false,
+            reason: `grant_failed_${grantStatus || "no_response"}`,
+          };
+        }
+
+        // Retry the original event POST exactly once.
+        let retryResponse;
+        try {
+          retryResponse = await fetchImpl(endpoint, requestInit, resolvedTimeoutMs);
+        } catch (retryError) {
+          recordCircuitFailure(outboundCircuit, normalizedNowMs);
+          return {
+            synced: false,
+            reason: normalizeString(retryError?.message) || "sync_failed",
+          };
+        }
+        if (retryResponse && retryResponse.ok) {
+          recordCircuitSuccess(outboundCircuit);
+          return {
+            synced: true,
+            status: retryResponse.status,
+            autoGranted: true,
+          };
+        }
+        recordCircuitFailure(outboundCircuit, normalizedNowMs);
+        return {
+          synced: false,
+          reason: `api_${retryResponse ? retryResponse.status : "no_response"}`,
+        };
+      }
+    }
+
+    recordCircuitFailure(outboundCircuit, normalizedNowMs);
     return {
-      synced: true,
-      status: response.status,
+      synced: false,
+      reason: `api_${response ? response.status : "no_response"}`,
     };
   } catch (error) {
     recordCircuitFailure(outboundCircuit, normalizedNowMs);
@@ -622,6 +840,7 @@ export async function pollHumanMessages(
     since = null,
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
     limit = HUMAN_MESSAGE_FETCH_LIMIT,
+    forceCircuitProbe = false,
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetchWithTimeout,
     nowMs = Date.now,
@@ -638,7 +857,7 @@ export async function pollHumanMessages(
   }
 
   const normalizedNowMs = Number(nowMs()) || Date.now();
-  if (isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+  if (!forceCircuitProbe && isCircuitOpen(inboundCircuit, normalizedNowMs)) {
     return {
       ok: false,
       reason: "circuit_breaker_open",
@@ -781,6 +1000,7 @@ export async function pollSessionEvents(
     since = null,
     limit = 200,
     timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    forceCircuitProbe = false,
     resolveAuthSession = resolveActiveAuthSession,
     fetchImpl = fetchWithTimeout,
     nowMs = Date.now,
@@ -797,7 +1017,7 @@ export async function pollSessionEvents(
   }
 
   const normalizedNowMs = Number(nowMs()) || Date.now();
-  if (isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+  if (!forceCircuitProbe && isCircuitOpen(inboundCircuit, normalizedNowMs)) {
     return {
       ok: false,
       reason: "circuit_breaker_open",
@@ -836,7 +1056,10 @@ export async function pollSessionEvents(
   if (normalizedSince) {
     query.set("after", normalizedSince);
   }
-  query.set("limit", String(Math.max(1, Math.min(200, normalizePositiveInteger(limit, 200)))));
+  query.set(
+    "limit",
+    String(Math.max(1, Math.min(SESSION_EVENT_FETCH_LIMIT, normalizePositiveInteger(limit, SESSION_EVENT_FETCH_LIMIT))))
+  );
   const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events?${query.toString()}`;
 
   try {
@@ -889,6 +1112,131 @@ export async function pollSessionEvents(
   }
 }
 
+/**
+ * Poll the latest durable session events page via the reverse-history endpoint.
+ *
+ * This powers `sl session read --remote --tail`: a forward cursor can be many
+ * pages behind in long rooms, but a tail read must show the latest messages now.
+ * The API returns newest-first for `/events/before`; callers get chronological
+ * order so appending/displaying matches the local NDJSON stream.
+ */
+export async function pollSessionEventsBefore(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    beforeSequence = null,
+    limit = 50,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+    forceCircuitProbe = false,
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    nowMs = Date.now,
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return {
+      ok: false,
+      reason: "invalid_session_id",
+      events: [],
+      cursor: null,
+      beforeSequence: null,
+    };
+  }
+
+  const normalizedNowMs = Number(nowMs()) || Date.now();
+  if (!forceCircuitProbe && isCircuitOpen(inboundCircuit, normalizedNowMs)) {
+    return {
+      ok: false,
+      reason: "circuit_breaker_open",
+      events: [],
+      cursor: null,
+      beforeSequence: null,
+    };
+  }
+
+  let session = null;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return {
+      ok: false,
+      reason: "no_session",
+      events: [],
+      cursor: null,
+      beforeSequence: null,
+    };
+  }
+  if (!session || !session.token) {
+    return {
+      ok: false,
+      reason: "not_authenticated",
+      events: [],
+      cursor: null,
+      beforeSequence: null,
+    };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  const normalizedBeforeSequence = Number(beforeSequence);
+  if (Number.isFinite(normalizedBeforeSequence) && normalizedBeforeSequence > 0) {
+    query.set("beforeSequence", String(Math.floor(normalizedBeforeSequence)));
+  }
+  query.set(
+    "limit",
+    String(Math.max(1, Math.min(SESSION_EVENT_FETCH_LIMIT, normalizePositiveInteger(limit, 50))))
+  );
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/events/before?${query.toString()}`;
+
+  try {
+    const response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)
+    );
+    if (!response || !response.ok) {
+      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      return {
+        ok: false,
+        reason: `api_${response ? response.status : "no_response"}`,
+        events: [],
+        cursor: null,
+        beforeSequence: Number.isFinite(normalizedBeforeSequence) ? normalizedBeforeSequence : null,
+      };
+    }
+    const payload = await response.json().catch(() => ({}));
+    recordCircuitSuccess(inboundCircuit);
+
+    const events = chronologicalSessionEvents(payload?.events || []);
+    const lastEvent = events[events.length - 1] || null;
+    const firstEvent = events[0] || null;
+    return {
+      ok: true,
+      reason: "",
+      events,
+      cursor: normalizeString(lastEvent?.cursor) || null,
+      beforeSequence: eventSequenceNumber(firstEvent) || null,
+    };
+  } catch (error) {
+    recordCircuitFailure(inboundCircuit, normalizedNowMs);
+    return {
+      ok: false,
+      reason: normalizeString(error?.message) || "poll_failed",
+      events: [],
+      cursor: null,
+      beforeSequence: Number.isFinite(normalizedBeforeSequence) ? normalizedBeforeSequence : null,
+    };
+  }
+}
+
 
 /**
  * List sessions owned by the active user via `GET /api/v1/sessions`.
@@ -1052,6 +1400,7 @@ export function resetSessionSyncStateForTests() {
   inboundCircuit.openedAtMs = 0;
   sessionIngestWindowBySessionId.clear();
   humanRelayWindowBySessionId.clear();
+  autoGrantAttemptedAgentIds.clear();
   // Tests that exercise the network path explicitly need the
   // SENTINELAYER_SKIP_REMOTE_SYNC guard off — otherwise the function
   // short-circuits before the mocked fetchImpl is ever called. Tests that

package/src/session/title-sync.js

@@ -0,0 +1,107 @@
+import process from "node:process";
+
+import { SentinelayerApiError, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { recordSessionRemoteTitleSync } from "./store.js";
+
+const DEFAULT_TITLE_SYNC_TIMEOUT_MS = 2_000;
+const DEFAULT_TITLE_SYNC_RETRY_DELAY_MS = 200;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function remoteSessionSyncDisabled(env = process.env) {
+  return String(env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1";
+}
+
+function normalizeFailureReason(error) {
+  if (error instanceof SentinelayerApiError) {
+    return error.code || `api_${error.status || "error"}`;
+  }
+  return normalizeString(error?.message) || "sync_failed";
+}
+
+function isTerminalTitleSyncError(error) {
+  return (
+    error instanceof SentinelayerApiError &&
+    (error.status === 422 || error.code === "INVALID_SESSION_TITLE")
+  );
+}
+
+export async function pushSessionTitleToApi(
+  sessionId,
+  title,
+  {
+    targetPath,
+    env = process.env,
+    timeoutMs = DEFAULT_TITLE_SYNC_TIMEOUT_MS,
+    maxRetries = 1,
+    retryDelayMs = DEFAULT_TITLE_SYNC_RETRY_DELAY_MS,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+    recordRemoteTitleSync = recordSessionRemoteTitleSync,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedTitle = normalizeString(title);
+  if (!normalizedSessionId || !normalizedTitle) {
+    return { synced: false, reason: "invalid_input" };
+  }
+  if (remoteSessionSyncDisabled(env)) {
+    return { synced: false, reason: "remote_sync_disabled" };
+  }
+
+  await recordRemoteTitleSync(normalizedSessionId, {
+    targetPath,
+    title: normalizedTitle,
+    pending: true,
+    failureReason: "pending",
+  }).catch(() => null);
+
+  try {
+    const session = await resolveAuthSession({
+      cwd: targetPath,
+      env,
+      autoRotate: true,
+    });
+    if (!session?.token || !session?.apiUrl) {
+      await recordRemoteTitleSync(normalizedSessionId, {
+        targetPath,
+        title: normalizedTitle,
+        pending: true,
+        failureReason: "not_authenticated",
+      }).catch(() => null);
+      return { synced: false, reason: "not_authenticated" };
+    }
+    const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+    const result = await requestMutation(
+      `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/title`,
+      {
+        method: "POST",
+        operationName: "session.set_title",
+        headers: { Authorization: `Bearer ${session.token}` },
+        body: { title: normalizedTitle },
+        timeoutMs,
+        maxRetries,
+        retryDelayMs,
+      },
+    );
+    await recordRemoteTitleSync(normalizedSessionId, {
+      targetPath,
+      title: normalizedTitle,
+      pending: false,
+    }).catch(() => null);
+    return { synced: true, status: result?.status || 200 };
+  } catch (error) {
+    const reason = normalizeFailureReason(error);
+    const terminal = isTerminalTitleSyncError(error);
+    await recordRemoteTitleSync(normalizedSessionId, {
+      targetPath,
+      title: normalizedTitle,
+      pending: !terminal,
+      failureReason: reason,
+    }).catch(() => null);
+    return { synced: false, reason, terminal };
+  }
+}