sentinelayer-cli 0.43.0 → 0.45.0

package/src/session/invitations.js

@@ -3,6 +3,7 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
+import { checkedTransport, credentialFor, credentialHmac, isAuthenticated, isCredential } from "../auth/credential-destinations.js";
 import { requestJsonMutation } from "../auth/http.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { renderCoordinationBulletList } from "./coordination-guidance.js";
@@ -30,6 +31,16 @@ export function canonicalSessionRef(value) {
   return raw.toLowerCase();
 }
 
+function sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey } = {}) {
+  return [
+    "session-mutation-csrf:v1",
+    canonicalSessionRef(sessionId),
+    normalizeString(routeId),
+    normalizeString(idempotencyKey),
+  ].join("\0");
+}
+
+// The API's CSRF proof for a given bearer: what the server (or a test fixture) checks against.
 export function createSessionMutationCsrfToken({
   bearerToken,
   sessionId,
@@ -38,35 +49,29 @@ export function createSessionMutationCsrfToken({
 } = {}) {
   const secret = normalizeString(bearerToken);
   if (!secret) return "";
-  const message = [
-    "session-mutation-csrf:v1",
-    canonicalSessionRef(sessionId),
-    normalizeString(routeId),
-    normalizeString(idempotencyKey),
-  ].join("\0");
-  return createHmac("sha256", secret).update(message, "utf-8").digest("hex");
+  return createHmac("sha256", secret)
+    .update(sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey }), "utf-8")
+    .digest("hex");
 }
 
+// The session-mutation headers: origin and a CSRF proof derived from the credential the request
+// is sent with. The credential itself is attached by credentialedRequest, never here.
 export function createSessionMutationHeaders({
-  bearerToken,
+  credential,
   sessionId,
   routeId,
   idempotencyKey,
   origin = SESSION_MUTATION_ORIGIN,
 } = {}) {
-  const token = normalizeString(bearerToken);
   const normalizedOrigin = normalizeString(origin) || SESSION_MUTATION_ORIGIN;
   return {
-    Authorization: `Bearer ${token}`,
     Origin: normalizedOrigin,
     "Sec-Fetch-Site": "same-site",
     "X-Sentinelayer-Session-Mutation": "session-mutation",
-    "X-CSRF-Token": createSessionMutationCsrfToken({
-      bearerToken: token,
-      sessionId,
-      routeId,
-      idempotencyKey,
-    }),
+    // keyed inside src/auth/credential-destinations.js; the token never leaves it
+    "X-CSRF-Token": isCredential(credential)
+      ? credentialHmac(credential, sessionMutationCsrfMessage({ sessionId, routeId, idempotencyKey }))
+      : "",
   };
 }
 
@@ -106,10 +111,11 @@ export async function acceptSessionInvitation(
     env: process.env,
     autoRotate: false,
   });
-  if (!auth?.token || !auth?.apiUrl) {
+  if (!isAuthenticated(auth) || !auth?.apiUrl) {
     throw new Error("Not authenticated. Run `sl auth login` first.");
   }
 
+  const credential = await credentialFor(auth);
   const resolvedIdempotencyKey =
     normalizeString(idempotencyKey) || createSessionMutationIdempotencyKey("session-invite-accept");
   const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
@@ -121,14 +127,15 @@ export async function acceptSessionInvitation(
   if (normalizedSeatKey) body.seatKey = normalizedSeatKey;
   if (normalizedAgentId) body.agentId = normalizedAgentId;
 
-  const result = await requestMutation(
+  const result = await checkedTransport(requestMutation)(
     `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
     {
       method: "POST",
       operationName: "session.invitation_accept",
       idempotencyKey: resolvedIdempotencyKey,
+      credential,
       headers: createSessionMutationHeaders({
-        bearerToken: auth.token,
+        credential,
         sessionId: normalizedSessionId,
         routeId: SESSION_INVITATION_ACCEPT_ROUTE_ID,
         idempotencyKey: resolvedIdempotencyKey,

package/src/session/live-source.js

@@ -18,6 +18,7 @@
 import fs from "node:fs";
 import { setTimeout as sleep } from "node:timers/promises";
 
+import { CredentialDestinationRefused, credentialedRequest } from "../auth/credential-destinations.js";
 import { resolveSessionPaths } from "./paths.js";
 import { readStream } from "./stream.js";
 import {
@@ -155,12 +156,12 @@ export async function* watchLocalStream({
 export async function* watchRemoteStream({
   apiBaseUrl,
   sessionId,
-  token,
+  credential,
   signal,
   _sseFetch = fetch,
   reconnectBackoffMs = DEFAULT_RECONNECT_BACKOFF_MS,
 } = {}) {
-  if (!apiBaseUrl || !sessionId || !token) return;
+  if (!apiBaseUrl || !sessionId || !credential) return;
   const endpoint = `${apiBaseUrl.replace(/\/+$/, "")}/api/v1/sessions/${encodeURIComponent(
     sessionId,
   )}/stream`;
@@ -182,17 +183,16 @@ export async function* watchRemoteStream({
         ? `${endpoint}?fromSequence=${encodeURIComponent(String(resumeSequence))}`
         : endpoint;
     try {
-      response = await _sseFetch(url, {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          Accept: "text/event-stream",
-        },
-        signal,
-      });
+      response = await credentialedRequest(
+        credential,
+        url,
+        { method: "GET", headers: { Accept: "text/event-stream" }, signal },
+        { fetchImpl: _sseFetch },
+      );
     } catch (err) {
       if (signal?.aborted) return;
       yield { source: "sse", error: String(err?.message || err) };
+      if (err instanceof CredentialDestinationRefused) return; // final: no reconnect can change it
       await sleep(backoff);
       backoff = Math.min(backoff * 2, MAX_RECONNECT_BACKOFF_MS);
       continue;
@@ -267,7 +267,7 @@ export async function* mergeLiveSources({
   sessionId,
   targetPath,
   apiBaseUrl,
-  token,
+  credential,
   signal,
   _localIterator,
   _remoteIterator,
@@ -278,10 +278,10 @@ export async function* mergeLiveSources({
     ? _localIterator
     : watchLocalStream({ sessionId, targetPath, signal });
   const remoteIterable =
-    _remoteIterator || (apiBaseUrl && token)
+    _remoteIterator || (apiBaseUrl && credential)
       ? _remoteIterator
         ? _remoteIterator
-        : watchRemoteStream({ apiBaseUrl, sessionId, token, signal })
+        : watchRemoteStream({ apiBaseUrl, sessionId, credential, signal })
       : null;
 
   const seen = new Map();

package/src/session/reactions.js

@@ -0,0 +1,258 @@
+// reactions.js -- the ONE path every like / dislike / unlike / undislike takes, from
+// the native CLI (`sl session react|action`) and the local MCP server
+// (`session_react`, `session_action`) alike.
+//
+// Three guarantees. Separate copies of this logic once broke each of them:
+//
+//   1. Authority. The write runs inside withAgentAdmission for (session, agent): an
+//      admitted agent acts on ITS admission credential, a tombstoned (expired,
+//      malformed, mis-bound) admission is refused before any request, and nothing
+//      falls back to the human's broader token or legacy agent grants.
+//   2. Intent. The API replays a reused idempotency key instead of acting on it
+//      (sentinelayer-api#914 reaction contract), so a key derived from
+//      (type, target, actor) makes like -> unlike -> like a silent no-op. Each NEW
+//      intent gets a fresh operation key. An explicit key is a retry of the intent
+//      that minted it, and is sent unchanged.
+//   3. Truth. Every result names its outcome and carries its operation key, so an
+//      ambiguous failure (the request may have landed) can be retried as the SAME
+//      intent instead of becoming a new one that could retract a newer reaction.
+
+import { randomBytes } from "node:crypto";
+import process from "node:process";
+
+import { assertCanonicalAgentId, canonicalAgentId, withAgentAdmission } from "./admission-auth.js";
+import { createSessionMessageAction } from "./sync.js";
+
+export const SESSION_REACTION_TYPES = Object.freeze(["like", "dislike", "unlike", "undislike"]);
+const REACTION_TYPES = new Set(SESSION_REACTION_TYPES);
+const UNDO_TARGETS = new Map([
+  ["unlike", "like"],
+  ["undislike", "dislike"],
+]);
+
+// createSessionMessageAction failures that happen before any request leaves this machine.
+const NOT_SENT_REASONS = new Set([
+  "invalid_input",
+  "remote_sync_disabled_env",
+  "circuit_breaker_open",
+  "no_session",
+  "not_authenticated",
+]);
+
+/**
+ * Every outcome a reaction can have. `ok` is true only for the first three.
+ *   applied     -- this request recorded a new reaction row
+ *   no_op       -- an equal reaction was already active; nothing changed. With
+ *                  `collapsedActionId` the server retained this request as evidence.
+ *   replayed    -- an explicit (retry) key had already been recorded; the server
+ *                  returned that original result and did not re-check current state
+ *   not_active  -- an undo with nothing of this actor's active to retract (409)
+ *   unsupported -- a server without reaction undo rejected the action value (422)
+ *   refused     -- any other definitive refusal; nothing was recorded
+ *   not_sent    -- the request never left this machine; nothing was recorded
+ *   unknown     -- the request may or may not have been recorded (timeout, lost
+ *                  response, 5xx): retry with the SAME operation key
+ */
+export const SESSION_REACTION_OUTCOMES = Object.freeze([
+  "applied",
+  "no_op",
+  "replayed",
+  "not_active",
+  "unsupported",
+  "refused",
+  "not_sent",
+  "unknown",
+]);
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+export function isSessionReactionType(value) {
+  return REACTION_TYPES.has(normalizeString(value).toLowerCase());
+}
+
+/** The like/dislike an undo retracts, or "" for a non-undo. */
+export function reactionUndoTarget(value) {
+  return UNDO_TARGETS.get(normalizeString(value).toLowerCase()) || "";
+}
+
+function targetKey({ targetSequenceId, targetCursor, targetActionId }) {
+  if (normalizeString(targetActionId)) return `action:${normalizeString(targetActionId)}`;
+  if (targetSequenceId) return `seq:${targetSequenceId}`;
+  return `cursor:${normalizeString(targetCursor)}`;
+}
+
+function targetLabel({ targetSequenceId, targetCursor, targetActionId }) {
+  if (normalizeString(targetActionId)) return `reply ${normalizeString(targetActionId)}`;
+  if (targetSequenceId) return `#${targetSequenceId}`;
+  return normalizeString(targetCursor) || "target";
+}
+
+/** A key for a NEW intent. Never derived from (type, target, actor) alone. */
+export function newReactionOperationKey({ surface, reaction, agentId, ...target } = {}) {
+  return `${surface}:${reaction}:${targetKey(target)}:${agentId}:${randomBytes(8).toString("hex")}`;
+}
+
+/**
+ * The exact 422 a server without reaction undo (sentinelayer-api before #914) returns
+ * for this action: FastAPI's validation envelope around the route's action-type
+ * validator, a single entry echoing the value sent. Anything looser could relabel a
+ * different validation failure as "undo unsupported", so the match is exact.
+ */
+export function isUndoUnsupportedValidationError(result = {}, actionType = "") {
+  if (result.status !== 422) return false;
+  const detail = result.error?.detail;
+  if (!Array.isArray(detail) || detail.length !== 1) return false;
+  const [entry] = detail;
+  return (
+    entry?.type === "value_error" &&
+    Array.isArray(entry.loc) &&
+    entry.loc.length === 2 &&
+    entry.loc[0] === "body" &&
+    entry.loc[1] === "actionType" &&
+    entry.msg === "Value error, unsupported message action type" &&
+    entry.input === actionType
+  );
+}
+
+function classify(reaction, result, retry) {
+  const status = Number.isInteger(result?.status) ? result.status : null;
+  if (result?.ok && result.action) {
+    if (normalizeString(result.collapsedActionId)) return "no_op";
+    if (result.duplicate) return retry ? "replayed" : "no_op";
+    return "applied";
+  }
+  if (status === null) {
+    return NOT_SENT_REASONS.has(normalizeString(result?.reason)) ? "not_sent" : "unknown";
+  }
+  if (status >= 500) return "unknown";
+  if (isUndoUnsupportedValidationError(result, reaction)) return "unsupported";
+  if (status === 409 && reactionUndoTarget(reaction) && result.error?.error?.code === "REACTION_NOT_ACTIVE") {
+    return "not_active";
+  }
+  if (status >= 400) return "refused";
+  return "unknown";
+}
+
+function describe(outcome, { reaction, agentId, target, operationKey, reason, errorCode, collapsedActionId }) {
+  const where = targetLabel(target);
+  switch (outcome) {
+    case "applied":
+      return `${agentId} ${reaction} recorded on ${where}.`;
+    case "no_op":
+      return (
+        `No change: ${agentId} already has an active ${reaction} on ${where}.` +
+        (collapsedActionId ? ` This request is retained as evidence ${collapsedActionId}.` : "")
+      );
+    case "replayed":
+      return (
+        `Replayed: operation ${operationKey} was already recorded. The server returned its ` +
+        `original result and did not re-check the current state.`
+      );
+    case "not_active":
+      return `Nothing to undo: ${agentId} has no active ${reactionUndoTarget(reaction)} on ${where}.`;
+    case "unsupported":
+      return `This server doesn't support undo yet (no '${reaction}' action). Nothing was changed.`;
+    case "refused":
+      return `The server refused this ${reaction} (${errorCode || reason}). Nothing was recorded.`;
+    case "not_sent":
+      return `Not sent (${reason}). Nothing was recorded.`;
+    default:
+      return (
+        `Outcome unknown (${reason || "no response"}): the server may have recorded this ${reaction}. ` +
+        `To retry this same intent, resend it with idempotency key ${operationKey}; ` +
+        `without that key it is a new intent.`
+      );
+  }
+}
+
+/**
+ * Submit one reaction. Throws only for invalid input or a refused admission (before
+ * any request); every server answer, network failure and timeout is an outcome.
+ */
+export async function submitSessionReaction({
+  surface,
+  sessionId,
+  agentId,
+  reaction,
+  targetSequenceId = null,
+  targetCursor = "",
+  targetActionId = "",
+  note = "",
+  idempotencyKey = "",
+  targetPath = process.cwd(),
+  timeoutMs = 15_000,
+  dryRun = false,
+  createSessionMessageActionFn = createSessionMessageAction,
+} = {}) {
+  const sid = normalizeString(sessionId);
+  const type = normalizeString(reaction).toLowerCase();
+  if (!sid) throw new Error("session id is required.");
+  if (!REACTION_TYPES.has(type)) {
+    throw new Error(`reaction must be one of: ${SESSION_REACTION_TYPES.join(", ")}.`);
+  }
+  // One canonical identity for authorisation and execution (see admission-auth.js).
+  assertCanonicalAgentId(agentId, "agentId");
+  const agent = canonicalAgentId(agentId);
+  if (!agent) throw new Error("agentId is required.");
+  const target = {
+    targetSequenceId: targetSequenceId || null,
+    targetCursor: normalizeString(targetCursor),
+    targetActionId: normalizeString(targetActionId),
+  };
+  if (!target.targetSequenceId && !target.targetCursor && !target.targetActionId) {
+    throw new Error("Provide a target sequence, cursor, or action id.");
+  }
+  const explicitKey = normalizeString(idempotencyKey);
+  const operationKey =
+    explicitKey || newReactionOperationKey({ surface, reaction: type, agentId: agent, ...target });
+  const base = {
+    sessionId: sid,
+    agentId: agent,
+    actionType: type,
+    ...target,
+    note: normalizeString(note),
+    operationKey,
+    idempotencyKey: operationKey,
+    retry: Boolean(explicitKey),
+  };
+  if (dryRun) return { ok: true, dryRun: true, outcome: "dry_run", ...base };
+
+  const result = await withAgentAdmission(sid, agent, () =>
+    createSessionMessageActionFn(sid, {
+      actionType: type,
+      targetPath,
+      ...target,
+      note: base.note,
+      metadata: { source: surface, agentId: agent },
+      idempotencyKey: operationKey,
+      timeoutMs,
+    }),
+  );
+  const outcome = classify(type, result, base.retry);
+  const collapsedActionId = normalizeString(result?.collapsedActionId) || null;
+  const status = Number.isInteger(result?.status) ? result.status : null;
+  const reason = normalizeString(result?.reason);
+  const errorCode = normalizeString(result?.error?.error?.code) || null;
+  return {
+    ok: outcome === "applied" || outcome === "no_op" || outcome === "replayed",
+    outcome,
+    ...base,
+    duplicate: Boolean(result?.duplicate),
+    collapsedActionId,
+    status,
+    reason,
+    errorCode,
+    message: describe(outcome, {
+      reaction: type,
+      agentId: agent,
+      target,
+      operationKey,
+      reason,
+      errorCode,
+      collapsedActionId,
+    }),
+    action: result?.ok && result.action ? result.action : null,
+  };
+}

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";
+}