sentinelayer-cli 0.44.0 → 0.46.0

package/src/session/route-classes.js

@@ -0,0 +1,107 @@
+// route-classes.js -- the ONE classification of every local MCP session tool ("mcp:<tool>")
+// and every `sl session` command the MCP CLI bridge can invoke ("cli:session <path>").
+//
+// In an agent context it decides what a route may do when the session it acts in stores NO
+// admission on this machine (when the session stores one, every route binds to it or is
+// refused; see runInSessionToolContext in src/mcp/session-stdio-server.js and
+// assertDispatchMatchesScope in src/session/admission-auth.js):
+//
+//   legacy-data-plane  a compatibility list for rooms that don't require admission:
+//                      posting, replying, reading/polling, message actions and reactions,
+//                      attention requests. Runs as before; the server's admission mode
+//                      decides whether a room accepts it.
+//   control            leases, locks, guards, tickets, checkpoints, joining and leaving,
+//                      listeners, room setup and everything else that is not plain
+//                      data-plane traffic. Refused unless the session's admission binds it.
+//   owner              room owner actions. Refused in an agent context.
+//   exempt-local       sends no request (a local store or built-in constants only).
+//
+// A route missing from this table is treated as unclassified and refused like control. A
+// unit test derives every MCP tool and every bridge-invokable command from the real handlers
+// and command tree and fails when one is missing here.
+
+export const SESSION_ROUTE_CLASSES = Object.freeze({
+  // ---- local MCP session tools
+  "mcp:poll_inbox": "legacy-data-plane",
+  "mcp:read_history": "legacy-data-plane",
+  "mcp:send_message": "legacy-data-plane",
+  "mcp:attention_request": "legacy-data-plane",
+  "mcp:session_action": "legacy-data-plane",
+  "mcp:session_react": "legacy-data-plane",
+  "mcp:session_reply": "legacy-data-plane",
+  "mcp:session_lock": "control",
+  "mcp:session_unlock": "control",
+  "mcp:session_locks": "control",
+  "mcp:memory.write": "exempt-local",
+  "mcp:memory.recall": "exempt-local",
+  "mcp:memory.summarize": "exempt-local",
+
+  // ---- `sl session` commands invokable through the MCP CLI bridge
+  "cli:session say": "legacy-data-plane",
+  "cli:session post-agent": "legacy-data-plane",
+  "cli:session observe": "legacy-data-plane",
+  "cli:session reply": "legacy-data-plane",
+  "cli:session comment": "legacy-data-plane",
+  "cli:session action": "legacy-data-plane",
+  "cli:session react": "legacy-data-plane",
+  "cli:session read": "legacy-data-plane",
+  "cli:session history": "legacy-data-plane",
+  "cli:session search": "legacy-data-plane",
+  "cli:session pins": "legacy-data-plane",
+  "cli:session lock": "control",
+  "cli:session unlock": "control",
+  "cli:session locks": "control",
+  "cli:session renew": "control",
+  "cli:session guard": "control",
+  "cli:session guard-hook": "control",
+  "cli:session guard-install": "control",
+  "cli:session guard-uninstall": "control",
+  "cli:session checkpoint create": "control",
+  "cli:session checkpoint generate": "control",
+  "cli:session checkpoint list": "control",
+  "cli:session checkpoint show": "control",
+  "cli:session ticket claim": "control",
+  "cli:session ticket events": "control",
+  "cli:session ticket list": "control",
+  "cli:session ticket release": "control",
+  "cli:session ticket renew": "control",
+  "cli:session ticket submit": "control",
+  "cli:session join": "control",
+  "cli:session leave": "control",
+  "cli:session stop-listener": "control",
+  "cli:session listeners": "control",
+  "cli:session set-title": "control",
+  "cli:session start": "control",
+  "cli:session ensure": "control",
+  "cli:session continue": "control",
+  "cli:session inject-guide": "control",
+  "cli:session setup-guides": "control",
+  "cli:session sync": "control",
+  "cli:session status": "control",
+  "cli:session list": "control",
+  "cli:session usage": "control",
+  "cli:session recall": "control",
+  "cli:session recap now": "control",
+  "cli:session edit": "control",
+  "cli:session wake codex": "control",
+  "cli:session wake codex-notify": "control",
+  "cli:session wake daemon": "control",
+  "cli:session access approve": "owner",
+  "cli:session access deny": "owner",
+  "cli:session access revoke": "owner",
+  "cli:session access mode": "owner",
+  "cli:session access request": "owner",
+  "cli:session access list": "owner",
+  "cli:session access status": "owner",
+  "cli:session actions": "exempt-local",
+  "cli:session templates": "exempt-local",
+});
+
+/** The compatibility list for rooms that don't require admission, as one named view of the table. */
+export const LEGACY_DATA_PLANE_TOOLS = Object.freeze(
+  Object.keys(SESSION_ROUTE_CLASSES).filter((route) => SESSION_ROUTE_CLASSES[route] === "legacy-data-plane"),
+);
+
+export function sessionRouteClass(route) {
+  return SESSION_ROUTE_CLASSES[route] || "unclassified";
+}

package/src/session/sync.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import process from "node:process";
 import { randomUUID } from "node:crypto";
 
+import { credentialedRequest, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { createAgentEvent } from "../events/schema.js";
 import { isSessionControlEvent } from "./control-events.js";
@@ -378,7 +379,8 @@ function recordCircuitFailure(circuit, nowMs) {
 
 // 401 and 403 refuse one credential (an expired, revoked or narrower agent admission, or
 // an identity the account has not granted). They say nothing about API health, so they
-// never count toward the machine-wide outbound breaker; every other failure does.
+// never count toward either machine-wide breaker (inbound or outbound): one agent's
+// refusals must not pause another agent's traffic. Network errors, timeouts and 5xx do.
 function isCredentialRefusal(response) {
   return Boolean(response) && (response.status === 401 || response.status === 403);
 }
@@ -388,6 +390,11 @@ function recordOutboundFailure(response, nowMs) {
   recordCircuitFailure(outboundCircuit, nowMs);
 }
 
+function recordInboundFailure(response, nowMs) {
+  if (isCredentialRefusal(response)) return;
+  recordCircuitFailure(inboundCircuit, nowMs);
+}
+
 function recordCircuitSuccess(circuit) {
   if (!circuit) {
     return;
@@ -671,13 +678,21 @@ export async function fetchJsonWithFullTimeout(
   const controller = new AbortController();
   const startedAtMs = Date.now();
   let response = null;
+  // A credential (src/auth/credential-destinations.js) is sent only to its own origin, by
+  // credentialedRequest; fetchImpl is the transport that it calls.
+  const { credential = null, ...init } = options || {};
   const requestOptions = {
-    ...options,
+    ...init,
     signal: combineAbortSignals([options?.signal, controller.signal]),
   };
+  const sent = credential
+    ? credentialedRequest(credential, url, requestOptions, {
+        fetchImpl: (target, request) => fetchImpl(target, request, resolvedTimeoutMs),
+      })
+    : fetchImpl(url, requestOptions, resolvedTimeoutMs);
 
   response = await withTimeout(
-    fetchImpl(url, requestOptions, resolvedTimeoutMs),
+    sent,
     resolvedTimeoutMs,
     {
       reason: "request_timeout",
@@ -1003,7 +1018,7 @@ export async function syncSessionEventToApi(
     return { synced: false, reason: "no_session" };
   }
 
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { synced: false, reason: "not_authenticated" };
   }
 
@@ -1017,8 +1032,8 @@ export async function syncSessionEventToApi(
     method: "POST",
     headers: {
       "Content-Type": "application/json",
-      Authorization: `Bearer ${session.token}`,
     },
+    credential: await credentialFor(session),
     body: requestBody,
   };
   const resolvedTimeoutMs = normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS);
@@ -1078,8 +1093,8 @@ export async function syncSessionEventToApi(
               method: "POST",
               headers: {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${session.token}`,
               },
+              credential: await credentialFor(session),
               body: JSON.stringify({
                 agent_id: agentId,
                 role: grantRole,
@@ -1201,7 +1216,7 @@ async function syncSessionAuxPayload(
   } catch {
     return { synced: false, reason: "no_session" };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { synced: false, reason: "not_authenticated" };
   }
 
@@ -1214,8 +1229,8 @@ async function syncSessionAuxPayload(
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
         },
+        credential: await credentialFor(session),
         body: JSON.stringify({
           ...payload,
           source: "cli",
@@ -1320,7 +1335,7 @@ export async function pollHumanMessages(
       cursor: normalizeString(since) || null,
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -1344,14 +1359,14 @@ export async function pollHumanMessages(
       {
         method: "GET",
         headers: {
-          Authorization: `Bearer ${session.token}`,
         },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -1487,7 +1502,7 @@ export async function pollSessionEvents(
       cursor: normalizeString(since) || null,
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -1518,7 +1533,7 @@ export async function pollSessionEvents(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
@@ -1536,7 +1551,7 @@ export async function pollSessionEvents(
           cursor: normalizedSince || null,
         };
       }
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -1655,7 +1670,7 @@ export async function fetchSessionPresence(
       present: [],
     };
   }
-  if (!session?.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -1672,7 +1687,7 @@ export async function fetchSessionPresence(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
@@ -1698,7 +1713,7 @@ export async function fetchSessionPresence(
           present: [],
         };
       }
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -1807,7 +1822,7 @@ export async function renewSessionPresence(
       recorded: false,
     };
   }
-  if (!session?.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -1836,8 +1851,8 @@ export async function renewSessionPresence(
         method: "PUT",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
         },
+        credential: await credentialFor(session),
         body: JSON.stringify(body),
         signal,
       },
@@ -1932,7 +1947,7 @@ export async function requestSessionListenerStop(
   } catch {
     return { ok: false, reason: "no_session", recorded: false };
   }
-  if (!session?.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", recorded: false };
   }
 
@@ -1952,9 +1967,9 @@ export async function requestSessionListenerStop(
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
           "Idempotency-Key": normalizedIdempotencyKey,
         },
+        credential: await credentialFor(session),
         body: JSON.stringify(body),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
@@ -2060,7 +2075,7 @@ export async function updateSessionReadCursor(
   } catch {
     return { ok: false, reason: "no_session", updated: false };
   }
-  if (!session?.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", updated: false };
   }
 
@@ -2081,8 +2096,8 @@ export async function updateSessionReadCursor(
         method: "PUT",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
         },
+        credential: await credentialFor(session),
         body: JSON.stringify(body),
         signal,
       },
@@ -2194,7 +2209,7 @@ export async function streamSessionEvents(
       errorCount: 0,
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -2244,18 +2259,18 @@ export async function streamSessionEvents(
 
   let response;
   try {
-    response = await fetchImpl(
+    response = await credentialedRequest(
+      await credentialFor(session),
       endpoint,
       {
         method: "GET",
         headers: {
           Accept: "text/event-stream",
-          Authorization: `Bearer ${session.token}`,
           ...(normalizedSince ? { "Last-Event-ID": normalizedSince } : {}),
         },
         signal: controller.signal,
       },
-      normalizedTimeoutMs
+      { fetchImpl: (target, init) => fetchImpl(target, init, normalizedTimeoutMs) },
     );
   } catch (error) {
     clearTimeout(timeoutHandle);
@@ -2415,7 +2430,7 @@ export async function pollSessionEventsBefore(
       beforeSequence: null,
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -2442,7 +2457,7 @@ export async function pollSessionEventsBefore(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
@@ -2460,7 +2475,7 @@ export async function pollSessionEventsBefore(
           beforeSequence: Number.isFinite(normalizedBeforeSequence) ? normalizedBeforeSequence : null,
         };
       }
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2538,7 +2553,7 @@ export async function listSessionMessageActions(
   } catch {
     return { ok: false, reason: "no_session", actions: [], count: 0, projection: null };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", actions: [], count: 0, projection: null };
   }
 
@@ -2563,13 +2578,13 @@ export async function listSessionMessageActions(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2643,7 +2658,7 @@ export async function fetchSessionUsageLedger(
   } catch {
     return { ok: false, reason: "no_session", status: 0, payload: null };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", status: 0, payload: null };
   }
 
@@ -2660,13 +2675,13 @@ export async function fetchSessionUsageLedger(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -2842,9 +2857,9 @@ export async function editSessionMessage(sessionId, {
   let auth;
   try { auth = await resolveAuthSession({ cwd: targetPath, env: process.env, autoRotate: false }); }
   catch { return { ok: false, reason: "no_session" }; }
-  if (!auth?.token) return { ok: false, reason: "not_authenticated" };
+  if (!isAuthenticated(auth)) return { ok: false, reason: "not_authenticated" };
   const base = `${resolveApiBaseUrl(auth)}/api/v1/sessions/${encodeURIComponent(sid)}`;
-  const headers = { Authorization: `Bearer ${auth.token}` };
+  const credential = await credentialFor(auth);
   const failure = (response, payload) => {
     const code = normalizeString(payload?.detail?.code || payload?.error?.code || payload?.code);
     // Client/schema/ownership conflicts are terminal and must not poison unrelated writes.
@@ -2857,7 +2872,7 @@ export async function editSessionMessage(sessionId, {
       const resource = replyId ? `replies/${encodeURIComponent(replyId)}` : messageId
         ? `messages/${encodeURIComponent(messageId)}` : `messages/by-sequence/${sequence}`;
       const authorQuery = normalizeString(agentId) ? `?agentId=${encodeURIComponent(normalizeString(agentId))}` : "";
-      const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}${authorQuery}`, { method: "GET", headers, signal }, timeoutMs, fetchImpl, { readErrorBody: true });
+      const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}${authorQuery}`, { method: "GET", credential, signal }, timeoutMs, fetchImpl, { readErrorBody: true });
       if (!response?.ok || payload?.ok === false) return failure(response, payload);
       const current = replyId ? payload?.reply : payload?.event;
       const fetchedRevision = Number(current?.messageRevision ?? 1);
@@ -2871,11 +2886,12 @@ export async function editSessionMessage(sessionId, {
     const { response, payload } = await fetchJsonWithFullTimeout(`${base}/${resource}`, {
       method: "PATCH",
       headers: {
-        ...createSessionMutationHeaders({ bearerToken: auth.token, sessionId: sid, routeId: replyId
+        ...createSessionMutationHeaders({ credential, sessionId: sid, routeId: replyId
           ? "PATCH /api/v1/sessions/{session_id}/replies/{action_id}"
           : "PATCH /api/v1/sessions/{session_id}/messages/{message_id}", idempotencyKey: mutationKey }),
         "Content-Type": "application/json", "Idempotency-Key": mutationKey,
       },
+      credential,
       body: JSON.stringify(body),
       signal,
     }, timeoutMs, fetchImpl, { readErrorBody: true });
@@ -2964,7 +2980,7 @@ export async function createSessionMessageAction(
   } catch {
     return { ok: false, reason: "no_session", action: null };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", action: null };
   }
 
@@ -3002,8 +3018,8 @@ export async function createSessionMessageAction(
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          Authorization: `Bearer ${session.token}`,
         },
+        credential: await credentialFor(session),
         body: JSON.stringify(body),
         signal,
       },
@@ -3104,7 +3120,7 @@ export async function searchSessionEvents(
       nextBeforeSequence: null,
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -3134,13 +3150,13 @@ export async function searchSessionEvents(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
     );
     if (!response || !response.ok) {
-      recordCircuitFailure(inboundCircuit, normalizedNowMs);
+      recordInboundFailure(response, normalizedNowMs);
       return {
         ok: false,
         reason: `api_${response ? response.status : "no_response"}`,
@@ -3226,7 +3242,7 @@ export async function listSessionsFromApi({
       warnings: [],
     };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return {
       ok: false,
       reason: "not_authenticated",
@@ -3262,7 +3278,7 @@ export async function listSessionsFromApi({
         endpoint,
         {
           method: "GET",
-          headers: { Authorization: `Bearer ${session.token}` },
+          credential: await credentialFor(session),
         },
         normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
         fetchImpl,
@@ -3368,7 +3384,7 @@ export async function fetchSessionFromApi(
   } catch {
     return { ok: false, reason: "no_session", session: null };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { ok: false, reason: "not_authenticated", session: null, status: 401 };
   }
 
@@ -3382,7 +3398,7 @@ export async function fetchSessionFromApi(
       endpoint,
       {
         method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
+        credential: await credentialFor(session),
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
@@ -3447,7 +3463,7 @@ export async function probeSessionAccess(
   } catch {
     return { accessible: false, reason: "no_session" };
   }
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { accessible: false, reason: "not_authenticated" };
   }
 
@@ -3458,13 +3474,11 @@ export async function probeSessionAccess(
 
   let response;
   try {
-    response = await fetchImpl(
+    response = await credentialedRequest(
+      await credentialFor(session),
       endpoint,
-      {
-        method: "GET",
-        headers: { Authorization: `Bearer ${session.token}` },
-      },
-      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+      { method: "GET" },
+      { fetchImpl: (target, init) => fetchImpl(target, init, normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS)) },
     );
   } catch (err) {
     return {