sentinelayer-cli 0.9.8 → 0.10.1

package/package.json

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

package/src/ai/proxy.js

@@ -27,7 +27,15 @@ const PROXY_RETRY_STATUSES = new Set([429, 502, 503, 504]);
  * @param {number} [options.temperature] - Temperature (default: 0.1)
  * @param {string} [options.apiUrl] - Override API URL
  * @param {string} [options.token] - Override Bearer token
- * @returns {Promise<{ text: string, usage: { inputTokens: number, outputTokens: number, costUsd: number, model: string, provider: string, latencyMs: number } }>}
+ * @param {string} [options.sessionId] - Optional Senti session id for server-side usage metering
+ * @param {string} [options.agentId] - Optional session agent id for server-side usage metering
+ * @param {string} [options.action] - Optional metered action, defaults server-side when omitted
+ * @param {string} [options.usageIdempotencyKey] - Stable per-intent key for proxy + ledger idempotency
+ * @param {string} [options.billingTier] - Optional billing tier hint
+ * @param {string} [options.customerPricingPolicy] - Optional customer pricing policy hint
+ * @param {object} [options.metadata] - Optional allowlisted billing metadata
+ * @param {Function} [options.fetchImpl] - Optional fetch implementation for tests
+ * @returns {Promise<{ text: string, usage: { inputTokens: number, outputTokens: number, costUsd: number, model: string, provider: string, latencyMs: number }, usageLedger: object | null }>}
  */
 export async function invokeViaProxy({
   prompt,
@@ -37,6 +45,14 @@ export async function invokeViaProxy({
   temperature = 0.1,
   apiUrl = "",
   token = "",
+  sessionId = "",
+  agentId = "",
+  action = "",
+  usageIdempotencyKey = "",
+  billingTier = "",
+  customerPricingPolicy = "",
+  metadata = null,
+  fetchImpl = fetch,
 } = {}) {
   // Resolve credentials from session if not provided
   let resolvedApiUrl = String(apiUrl || "").trim();
@@ -59,13 +75,40 @@ export async function invokeViaProxy({
 
   const url = `${resolvedApiUrl.replace(/\/+$/, "")}/api/v1/proxy/llm`;
 
-  const body = JSON.stringify({
+  const requestBody = {
     model,
     system_prompt: systemPrompt || "You are a code reviewer.",
     user_content: String(prompt || ""),
     max_tokens: maxTokens,
     temperature,
-  });
+  };
+
+  const normalizedSessionId = String(sessionId || "").trim();
+  const normalizedAgentId = String(agentId || "").trim();
+  const normalizedAction = String(action || "").trim();
+  const normalizedUsageIdempotencyKey = String(usageIdempotencyKey || "").trim();
+  const normalizedBillingTier = String(billingTier || "").trim();
+  const normalizedCustomerPricingPolicy = String(customerPricingPolicy || "").trim();
+  if (normalizedSessionId) requestBody.session_id = normalizedSessionId;
+  if (normalizedAgentId) requestBody.agent_id = normalizedAgentId;
+  if (normalizedAction) requestBody.action = normalizedAction;
+  if (normalizedUsageIdempotencyKey) requestBody.usage_idempotency_key = normalizedUsageIdempotencyKey;
+  if (normalizedBillingTier) requestBody.billing_tier = normalizedBillingTier;
+  if (normalizedCustomerPricingPolicy) requestBody.customer_pricing_policy = normalizedCustomerPricingPolicy;
+  if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+    requestBody.metadata = metadata;
+  }
+
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${resolvedToken}`,
+    Accept: "application/json",
+  };
+  if (normalizedUsageIdempotencyKey) {
+    headers["Idempotency-Key"] = normalizedUsageIdempotencyKey;
+  }
+
+  const body = JSON.stringify(requestBody);
 
   let response = null;
   let lastError = null;
@@ -75,13 +118,9 @@ export async function invokeViaProxy({
       const controller = new AbortController();
       const timeoutHandle = setTimeout(() => controller.abort(), PROXY_TIMEOUT_MS);
       try {
-        response = await fetch(url, {
+        response = await fetchImpl(url, {
           method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${resolvedToken}`,
-            Accept: "application/json",
-          },
+          headers,
           body,
           signal: controller.signal,
         });
@@ -131,6 +170,7 @@ export async function invokeViaProxy({
       provider: result.usage?.provider || "sentinelayer",
       latencyMs: result.usage?.latency_ms || 0,
     },
+    usageLedger: result.usageLedger || result.usage_ledger || null,
   };
 }
 

package/src/commands/session.js

@@ -347,14 +347,37 @@ async function ensureLocalSessionForRemoteCommand(
     }
     const existingStatus = normalizeString(existing.status).toLowerCase();
     const locallyClosedByStatus = existingStatus === "expired" || existingStatus === "archived";
+    let verifiedRemoteSession = remoteSession;
+    let verifiedRemoteStatus = normalizeString(
+      verifiedRemoteSession?.archiveStatus || verifiedRemoteSession?.status,
+    ).toLowerCase();
     if (locallyClosedByStatus && !skipRemoteProbe) {
+      const verification = await verifyRemoteSession(sessionId, { targetPath }).catch((error) => ({
+        ok: false,
+        reason: normalizeString(error?.message) || "verify_failed",
+      }));
+      if (!verification?.ok) {
+        throw new Error(
+          `Session '${sessionId}' is ${existingStatus} locally and remote verification failed (${verification?.reason || "unknown"}).`,
+        );
+      }
+      verifiedRemoteSession = verification.session || verifiedRemoteSession;
+      verifiedRemoteStatus = normalizeString(
+        verifiedRemoteSession?.archiveStatus || verifiedRemoteSession?.status,
+      ).toLowerCase();
+    }
+    if (
+      locallyClosedByStatus &&
+      verifiedRemoteStatus &&
+      !["active", "pending"].includes(verifiedRemoteStatus)
+    ) {
       throw new Error(
-        `Session '${sessionId}' is ${existingStatus} locally; run \`sl session join ${sessionId}\` to verify remote access before posting.`,
+        `Session '${sessionId}' is ${existingStatus} locally and remote status is ${verifiedRemoteStatus}; refusing to reopen a closed session.`,
       );
     }
 
-    let access = { accessible: Boolean(skipRemoteProbe), reason: "" };
-    if (!skipRemoteProbe) {
+    let access = { accessible: Boolean(skipRemoteProbe || locallyClosedByStatus), reason: "" };
+    if (!skipRemoteProbe && !locallyClosedByStatus) {
       access = await probeSessionAccess(sessionId, { targetPath }).catch((error) => ({
         accessible: false,
         reason: normalizeString(error?.message) || "probe_failed",
@@ -368,12 +391,13 @@ async function ensureLocalSessionForRemoteCommand(
 
     const refreshed = await refreshSessionCacheForRemoteActivity(sessionId, {
       targetPath,
-      title,
+      title: title || normalizeString(verifiedRemoteSession?.title),
+      expiresAt: normalizeString(verifiedRemoteSession?.expiresAt),
       lastInteractionAt:
-        normalizeString(remoteSession?.lastInteractionAt) ||
-        normalizeString(remoteSession?.lastActivityAt) ||
-        normalizeString(remoteSession?.updatedAt) ||
-        normalizeString(remoteSession?.createdAt),
+        normalizeString(verifiedRemoteSession?.lastInteractionAt) ||
+        normalizeString(verifiedRemoteSession?.lastActivityAt) ||
+        normalizeString(verifiedRemoteSession?.updatedAt) ||
+        normalizeString(verifiedRemoteSession?.createdAt),
     });
     return { materialized: false, refreshed: Boolean(refreshed), session: refreshed || existing };
   }
@@ -396,6 +420,13 @@ async function ensureLocalSessionForRemoteCommand(
     targetPath,
     sessionId,
     title: normalizeString(title) || `remote-${String(sessionId).slice(0, 8)}`,
+    createdAt: normalizeString(remoteSession?.createdAt),
+    expiresAt: normalizeString(remoteSession?.expiresAt),
+    lastInteractionAt:
+      normalizeString(remoteSession?.lastInteractionAt) ||
+      normalizeString(remoteSession?.lastActivityAt) ||
+      normalizeString(remoteSession?.updatedAt) ||
+      normalizeString(remoteSession?.createdAt),
   });
   return { materialized: true, refreshed: false, session: created };
 }

package/src/session/daemon.js

@@ -453,6 +453,10 @@ async function buildHelpResponseMessage(
       normalizePositiveInteger(daemonState.helpRequestTimeoutMs, HELP_REQUEST_TIMEOUT_MS) * 2
     )
   );
+  const requestCorrelationId =
+    normalizeString(requestEvent?.payload?.requestId) ||
+    normalizeString(requestEvent?.requestId) ||
+    normalizeIsoTimestamp(requestEvent?.ts, daemonState.startedAt);
 
   try {
     const llmResult = await runWithTimeout(
@@ -463,6 +467,15 @@ async function buildHelpResponseMessage(
           prompt: userPrompt,
           maxTokens: 320,
           temperature: 0.1,
+          sessionId: daemonState.sessionId,
+          agentId: SENTI_IDENTITY.id,
+          action: "proxy_llm",
+          usageIdempotencyKey: `senti:${daemonState.sessionId}:help:${requestCorrelationId}`,
+          billingTier: "internal",
+          metadata: {
+            purpose: "senti_help_response",
+            runId: requestCorrelationId,
+          },
         })
       ),
       llmTimeoutMs,

package/src/session/store.js

@@ -537,6 +537,7 @@ export async function refreshSessionCacheForRemoteActivity(
     targetPath = process.cwd(),
     title = "",
     ttlSeconds = DEFAULT_TTL_SECONDS,
+    expiresAt = "",
     lastInteractionAt = "",
     nowIso = new Date().toISOString(),
   } = {}
@@ -563,7 +564,7 @@ export async function refreshSessionCacheForRemoteActivity(
   const metadata = {
     ...loaded.metadata,
     updatedAt: nowIso,
-    expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+    expiresAt: normalizeIsoTimestamp(expiresAt, toIsoAfterSeconds(nowIso, normalizedTtlSeconds)),
     ttlSeconds: normalizedTtlSeconds,
     status: SESSION_STATUS_ACTIVE,
     expiredAt: null,

package/src/session/stream.js

@@ -6,13 +6,15 @@ import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
 import { enrichEventWithMentions } from "./mentions.js";
 import { resolveSessionPaths } from "./paths.js";
 import { redactEventPayload } from "./redact.js";
-import { syncSessionEventToApi } from "./sync.js";
+import { fetchSessionFromApi, listSessionsFromApi, syncSessionEventToApi } from "./sync.js";
 
 const DEFAULT_POLL_MS = 500;
 const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
 const DEFAULT_LOCK_STALE_MS = 30_000;
 const DEFAULT_LOCK_POLL_MS = 25;
 const DEFAULT_MAX_STREAM_EVENTS = 10_000;
+const DEFAULT_REMOTE_REFRESH_TTL_SECONDS = 24 * 60 * 60;
+const REMOTE_REFRESH_TIMEOUT_MS = 2_500;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -41,6 +43,15 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function toIsoAfterSeconds(baseIso, seconds) {
+  const baseEpoch = Date.parse(normalizeIsoTimestamp(baseIso, new Date().toISOString()));
+  const normalizedSeconds = normalizePositiveInteger(
+    seconds,
+    DEFAULT_REMOTE_REFRESH_TTL_SECONDS,
+  );
+  return new Date(baseEpoch + normalizedSeconds * 1000).toISOString();
+}
+
 async function readSessionMetadata(paths) {
   try {
     const raw = await fsp.readFile(paths.metadataPath, "utf-8");
@@ -64,6 +75,108 @@ async function writeSessionMetadata(paths, metadata = {}) {
   await fsp.rename(tmpPath, paths.metadataPath);
 }
 
+function remoteStatusAllowsLocalRefresh(remoteSession = {}) {
+  const status = normalizeString(remoteSession.archiveStatus || remoteSession.status).toLowerCase();
+  return !status || status === "active" || status === "pending";
+}
+
+function resolveRemoteSessionStatus(remoteSession = {}) {
+  return normalizeString(remoteSession.archiveStatus || remoteSession.status).toLowerCase();
+}
+
+async function resolveRemoteRefreshCandidate(sessionId, { targetPath = process.cwd() } = {}) {
+  const singletonResult = await fetchSessionFromApi(sessionId, {
+    targetPath,
+    timeoutMs: REMOTE_REFRESH_TIMEOUT_MS,
+  }).catch((error) => ({
+    ok: false,
+    reason: normalizeString(error?.message) || "fetch_failed",
+    session: null,
+  }));
+  if (singletonResult?.ok && singletonResult.session) {
+    if (!remoteStatusAllowsLocalRefresh(singletonResult.session)) {
+      return {
+        ok: false,
+        reason: `remote_${resolveRemoteSessionStatus(singletonResult.session) || "closed"}`,
+        remoteSession: singletonResult.session,
+      };
+    }
+    return { ok: true, reason: "", remoteSession: singletonResult.session };
+  }
+  if (singletonResult?.status && singletonResult.status !== 404) {
+    return { ok: false, reason: singletonResult.reason || `api_${singletonResult.status}` };
+  }
+
+  const listResult = await listSessionsFromApi({
+    targetPath,
+    includeArchived: true,
+    limit: 200,
+    timeoutMs: REMOTE_REFRESH_TIMEOUT_MS,
+  }).catch((error) => ({
+    ok: false,
+    reason: normalizeString(error?.message) || "list_failed",
+    sessions: [],
+  }));
+  if (listResult?.ok) {
+    const remoteSession = (listResult.sessions || []).find(
+      (entry) => normalizeString(entry?.sessionId) === sessionId,
+    );
+    if (remoteSession) {
+      if (!remoteStatusAllowsLocalRefresh(remoteSession)) {
+        return {
+          ok: false,
+          reason: `remote_${resolveRemoteSessionStatus(remoteSession) || "closed"}`,
+          remoteSession,
+        };
+      }
+      return { ok: true, reason: "", remoteSession };
+    }
+  }
+
+  return { ok: false, reason: listResult?.reason || singletonResult?.reason || "remote_unavailable" };
+}
+
+async function refreshExpiredMetadataFromRemote(paths, metadata = {}, { targetPath = process.cwd() } = {}) {
+  const candidate = await resolveRemoteRefreshCandidate(paths.sessionId, { targetPath });
+  if (!candidate?.ok) {
+    return { refreshed: false, reason: candidate?.reason || "remote_unavailable", metadata };
+  }
+  const remoteSession = candidate.remoteSession || {};
+  const nowIso = new Date().toISOString();
+  const ttlSeconds = normalizePositiveInteger(
+    metadata.ttlSeconds,
+    DEFAULT_REMOTE_REFRESH_TTL_SECONDS,
+  );
+  const remoteExpiresAt = normalizeString(remoteSession.expiresAt);
+  const remoteExpiryEpoch = Date.parse(remoteExpiresAt);
+  const nowEpoch = Date.parse(nowIso);
+  const expiresAt =
+    Number.isFinite(remoteExpiryEpoch) && Number.isFinite(nowEpoch) && remoteExpiryEpoch > nowEpoch
+      ? new Date(remoteExpiryEpoch).toISOString()
+      : toIsoAfterSeconds(nowIso, ttlSeconds);
+  const refreshed = {
+    ...metadata,
+    updatedAt: nowIso,
+    expiresAt,
+    ttlSeconds,
+    status: "active",
+    expiredAt: null,
+    archivedAt: null,
+    archiveStatus: resolveRemoteSessionStatus(remoteSession) || "active",
+    title: normalizeString(remoteSession.title) || metadata.title || null,
+    lastInteractionAt: normalizeIsoTimestamp(
+      remoteSession.lastInteractionAt ||
+        remoteSession.lastActivityAt ||
+        remoteSession.updatedAt ||
+        remoteSession.createdAt ||
+        metadata.lastInteractionAt,
+      metadata.lastInteractionAt || metadata.createdAt || nowIso,
+    ),
+  };
+  await writeSessionMetadata(paths, refreshed);
+  return { refreshed: true, reason: "", metadata: refreshed };
+}
+
 function isSessionExpired(metadata = {}, nowIso = new Date().toISOString()) {
   const status = normalizeString(metadata.status).toLowerCase();
   if (status === "expired" || status === "archived") {
@@ -227,12 +340,18 @@ export async function appendToStream(
   { targetPath = process.cwd(), maxEvents = DEFAULT_MAX_STREAM_EVENTS, syncRemote = true } = {}
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
-  const metadata = await readSessionMetadata(paths);
+  let metadata = await readSessionMetadata(paths);
   if (!metadata) {
     throw new Error(`Session '${paths.sessionId}' was not found.`);
   }
   if (isSessionExpired(metadata)) {
-    throw new Error(`Session '${paths.sessionId}' is expired and does not accept new events.`);
+    const refresh = await refreshExpiredMetadataFromRemote(paths, metadata, { targetPath });
+    if (!refresh.refreshed) {
+      throw new Error(
+        `Session '${paths.sessionId}' is expired and does not accept new events (remote refresh failed: ${refresh.reason}).`,
+      );
+    }
+    metadata = refresh.metadata;
   }
 
   const rawEvent = materializeCanonicalEvent(paths.sessionId, event);

package/src/session/sync.js

@@ -1319,6 +1319,91 @@ export async function listSessionsFromApi({
   };
 }
 
+/**
+ * Fetch one visible session row by id via `GET /api/v1/sessions/{id}`.
+ *
+ * The session-events read probe can prove membership, but it cannot prove the
+ * remote session is still active. Callers that need to refresh local closed
+ * metadata should use this status-bearing endpoint first, then fall back to
+ * `listSessionsFromApi` only for older API deployments without singleton read.
+ *
+ * @param {string} sessionId
+ * @param {object} [options]
+ * @param {string} [options.targetPath]
+ * @param {Function} [options.resolveAuthSession]
+ * @param {Function} [options.fetchImpl]
+ * @param {number} [options.timeoutMs]
+ * @returns {Promise<{ok: boolean, reason: string, session: object|null, status?: number}>}
+ */
+export async function fetchSessionFromApi(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { ok: false, reason: "invalid_session_id", session: null };
+  }
+
+  let session;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { ok: false, reason: "no_session", session: null };
+  }
+  if (!session || !session.token) {
+    return { ok: false, reason: "not_authenticated", session: null, status: 401 };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      reason: normalizeString(err?.message) || "fetch_failed",
+      session: null,
+    };
+  }
+  if (!response) {
+    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"
+        ? body
+        : null;
+    return { ok: true, reason: "", session: sessionPayload, status: response.status };
+  }
+  if (response.status === 403) {
+    return { ok: false, reason: "not_a_member", session: null, status: 403 };
+  }
+  if (response.status === 404) {
+    return { ok: false, reason: "session_not_found", session: null, status: 404 };
+  }
+  return { ok: false, reason: `api_${response.status}`, session: null, status: response.status };
+}
+
 /**
  * Probe whether a single session is visible to the active user.
  *