sentinelayer-cli 0.42.0 → 0.44.0

package/src/mcp/session-stdio-server.js

@@ -13,6 +13,12 @@ import { eventMatchesAgent } from "../session/listener.js";
 import { isSessionControlEvent } from "../session/control-events.js";
 import { buildObservations } from "../session/recall/observations.js";
 import { createMemoryService } from "../engram/index.js";
+import { assertCanonicalAgentId, canonicalAgentId, withAgentAdmission } from "../session/admission-auth.js";
+import {
+  SESSION_REACTION_TYPES,
+  isSessionReactionType,
+  submitSessionReaction,
+} from "../session/reactions.js";
 import {
   createSessionMessageAction,
   listSessionMessageActions,
@@ -44,9 +50,12 @@ const SESSION_MESSAGE_ACTION_TYPES = new Set([
   "reply",
   "like",
   "dislike",
+  "unlike",
+  "undislike",
   "disregard",
   "view",
 ]);
+const SESSION_REACT_TYPES = Object.freeze(["ack", ...SESSION_REACTION_TYPES]);
 const SESSION_MESSAGE_ACTION_ALIASES = new Map([["comment", "reply"]]);
 
 function normalizeString(value) {
@@ -701,6 +710,25 @@ async function runSessionAction({
   const normalizedActionType = normalizeSessionMessageActionType(actionType || input.actionType || input.action_type);
   const target = requireSessionActionTarget(input);
   const normalizedNote = truncateText(note || input.note || input.message || input.text || "").text;
+  if (isSessionReactionType(normalizedActionType)) {
+    // The same path as the native CLI: canonical fail-closed admission, a fresh
+    // operation key per new intent (an explicit idempotencyKey is a retry), and a
+    // truthful outcome. The raw agent id is passed so a non-canonical spelling is
+    // refused rather than silently aliased.
+    return submitSessionReaction({
+      surface: "mcp",
+      sessionId,
+      agentId: normalizeString(input.agentId || input.agent_id || input.agent),
+      reaction: normalizedActionType,
+      ...target,
+      note: normalizedNote,
+      idempotencyKey: normalizeString(input.idempotencyKey || input.idempotency_key),
+      targetPath,
+      timeoutMs: normalizePositiveInteger(input.timeoutMs || input.timeout_ms, 15_000),
+      dryRun: Boolean(input.dryRun || input.dry_run),
+      createSessionMessageActionFn,
+    });
+  }
   const idempotencyKey =
     normalizeString(input.idempotencyKey || input.idempotency_key) ||
     defaultActionIdempotencyKey({
@@ -858,6 +886,47 @@ async function persistSessionEvent({
   };
 }
 
+// Local MCP tools that act AS an agent: post, raise attention, react, reply, act on a
+// message, lease files, or advance that agent's read cursor. Each runs inside the
+// agent's admission scope, the same canonical path native `sl session` actor commands
+// use. A live stored admission is the only credential its requests carry; an expired,
+// malformed or mis-bound one is refused before any request; a credential the API
+// refuses (401/403) is final. With no stored admission a tool behaves as before.
+export const SESSION_MCP_ACTOR_TOOLS = Object.freeze([
+  "poll_inbox",
+  "read_history",
+  "send_message",
+  "attention_request",
+  "session_action",
+  "session_react",
+  "session_reply",
+  "session_lock",
+  "session_unlock",
+]);
+
+function actorAgentId(toolName, input = {}) {
+  const raw =
+    normalizeString(input.agentId || input.agent_id || input.agent) ||
+    (toolName === "read_history" ? normalizeString(process.env.SENTINELAYER_AGENT_ID) : "");
+  if (!raw) return "";
+  // One canonical identity for authorisation and execution (see admission-auth.js).
+  assertCanonicalAgentId(raw, "agentId");
+  return canonicalAgentId(raw);
+}
+
+function routeActorToolsThroughAdmission(handlers) {
+  for (const name of SESSION_MCP_ACTOR_TOOLS) {
+    const run = handlers[name];
+    handlers[name] = async (input = {}) => {
+      const agentId = actorAgentId(name, input);
+      // No agent named: the tool's own validation reports it (read_history reads as the user).
+      if (!agentId) return run(input);
+      return withAgentAdmission(requireSessionId(input), agentId, () => run(input));
+    };
+  }
+  return handlers;
+}
+
 export function createSessionMcpToolHandlers({
   targetPath = process.cwd(),
   pollSessionEventsFn = pollSessionEvents,
@@ -897,7 +966,7 @@ export function createSessionMcpToolHandlers({
       verified: false,
     };
   };
-  return {
+  const handlers = {
     async poll_inbox(input = {}) {
       const sessionId = requireSessionId(input);
       const agentId = requireAgentId(input);
@@ -1105,8 +1174,8 @@ export function createSessionMcpToolHandlers({
 
     async session_react(input = {}) {
       const reaction = normalizeSessionMessageActionType(input.reaction || input.actionType || input.action_type);
-      if (!["ack", "like", "dislike"].includes(reaction)) {
-        throw new Error("reaction must be one of: ack, like, dislike.");
+      if (!SESSION_REACT_TYPES.includes(reaction)) {
+        throw new Error(`reaction must be one of: ${SESSION_REACT_TYPES.join(", ")}.`);
       }
       return runSessionAction({
         input,
@@ -1267,6 +1336,7 @@ export function createSessionMcpToolHandlers({
       });
     },
   };
+  return routeActorToolsThroughAdmission(handlers);
 }
 
 export const SESSION_MCP_TOOLS = Object.freeze([
@@ -1419,7 +1489,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_action",
     title: "Record Senti Session Action",
     description:
-      "Record a low-noise message action such as ack, working_on, disregard, like, dislike, or reply; view advances the monotonic read cursor instead of appending an action.",
+      "Record a low-noise message action such as ack, working_on, disregard, like, dislike, unlike, undislike, or reply; view advances the monotonic read cursor instead of appending an action.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1442,7 +1512,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
     name: "session_react",
     title: "React To Senti Message",
     description:
-      "Acknowledge or react to a target session event with ack, like, or dislike.",
+      "Acknowledge or react to a target session event with ack, like, or dislike, or retract your own like/dislike with unlike/undislike. Reactions report an outcome and an operation key; resend that key as idempotencyKey only to retry the same intent.",
     inputSchema: {
       type: "object",
       additionalProperties: false,
@@ -1450,7 +1520,7 @@ export const SESSION_MCP_TOOLS = Object.freeze([
       properties: {
         sessionId: { type: "string", minLength: 1 },
         agentId: { type: "string", minLength: 1 },
-        reaction: { type: "string", enum: ["ack", "like", "dislike"] },
+        reaction: { type: "string", enum: [...SESSION_REACT_TYPES] },
         targetSequenceId: { type: "integer", minimum: 1 },
         targetCursor: { type: "string" },
         targetActionId: { type: "string" },

package/src/session/admission-access.js

@@ -0,0 +1,284 @@
+// Owner/delegator controls for the Agent Admission Contract.
+//
+// Agent-side key generation, approval polling, proof-of-possession claim, and
+// credential storage remain in admission.js. This module is deliberately the
+// human control plane only: inspect requests, approve/deny them, or revoke a
+// live grant. Every mutation uses the same session CSRF + idempotency contract
+// as the existing request/claim path.
+
+import process from "node:process";
+
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { hasStoredAdmissionCredentials } from "./admission.js";
+import { currentAdmittedAgent } from "./admission-auth.js";
+import {
+  SESSION_MUTATION_ORIGIN,
+  createSessionMutationHeaders,
+  createSessionMutationIdempotencyKey,
+} from "./invitations.js";
+
+/**
+ * Approve, deny, revoke and mode changes are the room owner's decisions, made with the
+ * owner's own session. They are unavailable while this process is an agent context:
+ * SENTINELAYER_AGENT_ID is set, an agent admission scope is in force, or this machine
+ * stores agent admission credentials. Checked before any credential lookup or request.
+ */
+export async function assertOwnerAccessContext({ env = process.env, homeDir } = {}) {
+  let why = "";
+  if (normalizeString(env.SENTINELAYER_AGENT_ID)) {
+    why = "SENTINELAYER_AGENT_ID is set";
+  } else if (currentAdmittedAgent()) {
+    why = "an agent admission is in use";
+  } else if (await hasStoredAdmissionCredentials({ homeDir })) {
+    why = "agent admission credentials are stored on this machine";
+  }
+  if (why) {
+    throw new Error(
+      `Access approve, deny, revoke and mode are owner actions and are unavailable in an agent context (${why}). ` +
+        `Use the room's web dashboard, or run the command from an environment without agent credentials.`,
+    );
+  }
+}
+
+export const ADMISSION_STATUSES = Object.freeze([
+  "pending",
+  "approved",
+  "active",
+  "denied",
+  "cancelled",
+  "expired",
+  "revoked",
+  "stopped",
+]);
+
+const ROUTES = Object.freeze({
+  decision: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/decision",
+  revoke: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/revoke",
+  mode: "POST /api/v1/sessions/{session_id}/admission-mode",
+});
+
+function normalizeString(value) {
+  return String(value ?? "").trim();
+}
+
+function required(value, label) {
+  const normalized = normalizeString(value);
+  if (!normalized) throw new Error(`${label} is required.`);
+  return normalized;
+}
+
+async function authContext(targetPath, resolveAuthSession) {
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth?.token || !auth?.apiUrl) {
+    throw new Error("Not authenticated. Run `sl auth login` first.");
+  }
+  return {
+    token: auth.token,
+    apiUrl: normalizeString(auth.apiUrl).replace(/\/+$/, ""),
+  };
+}
+
+function admissionsUrl(apiUrl, sessionId, suffix = "") {
+  return `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/admissions${suffix}`;
+}
+
+function boundedIdempotencyKey(value, operation) {
+  const explicit = normalizeString(value);
+  if (explicit.length > 128) throw new Error("--idempotency-key must be at most 128 characters.");
+  return explicit || createSessionMutationIdempotencyKey(operation);
+}
+
+async function mutateAdmission(
+  sessionId,
+  suffix,
+  routeId,
+  body,
+  {
+    targetPath,
+    idempotencyKey,
+    operationName,
+    origin,
+    resolveAuthSession,
+    requestMutation,
+  },
+) {
+  const key = boundedIdempotencyKey(idempotencyKey, operationName);
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const result = await requestMutation(admissionsUrl(auth.apiUrl, sessionId, suffix), {
+    method: "POST",
+    operationName,
+    idempotencyKey: key,
+    headers: createSessionMutationHeaders({
+      bearerToken: auth.token,
+      sessionId,
+      routeId,
+      idempotencyKey: key,
+      origin,
+    }),
+    body,
+  });
+  return { idempotencyKey: key, result };
+}
+
+export async function listSessionAdmissions(
+  sessionId,
+  {
+    status = "",
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestRead = requestJson,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const normalizedStatus = normalizeString(status).toLowerCase();
+  if (normalizedStatus && !ADMISSION_STATUSES.includes(normalizedStatus)) {
+    throw new Error(
+      `--status must be one of: ${ADMISSION_STATUSES.join(", ")}.`,
+    );
+  }
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const query = normalizedStatus ? `?status=${encodeURIComponent(normalizedStatus)}` : "";
+  return requestRead(`${admissionsUrl(auth.apiUrl, sid)}${query}`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${auth.token}` },
+  });
+}
+
+export async function getSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestRead = requestJson,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const auth = await authContext(targetPath, resolveAuthSession);
+  return requestRead(admissionsUrl(auth.apiUrl, sid, `/${encodeURIComponent(aid)}`), {
+    method: "GET",
+    headers: { Authorization: `Bearer ${auth.token}` },
+  });
+}
+
+export async function decideSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    decision,
+    grantedActions,
+    ttlSeconds,
+    note,
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const normalizedDecision = normalizeString(decision).toLowerCase();
+  if (!["approve", "deny"].includes(normalizedDecision)) {
+    throw new Error("decision must be approve or deny.");
+  }
+  if (normalizedDecision === "deny" && (grantedActions !== undefined || ttlSeconds !== undefined)) {
+    throw new Error("A denied admission cannot include --scope or --ttl.");
+  }
+  const body = { decision: normalizedDecision };
+  if (grantedActions !== undefined) body.grantedActions = grantedActions;
+  if (ttlSeconds !== undefined) body.ttlSeconds = ttlSeconds;
+  const normalizedNote = normalizeString(note);
+  if (normalizedNote) body.note = normalizedNote;
+  await assertOwnerAccessContext();
+  return mutateAdmission(
+    sid,
+    `/${encodeURIComponent(aid)}/decision`,
+    ROUTES.decision,
+    body,
+    {
+      targetPath,
+      idempotencyKey,
+      operationName: `session.admission_${normalizedDecision}`,
+      origin,
+      resolveAuthSession,
+      requestMutation,
+    },
+  );
+}
+
+export async function revokeSessionAdmission(
+  sessionId,
+  admissionId,
+  {
+    reason,
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const aid = required(admissionId, "admission id");
+  const normalizedReason = normalizeString(reason);
+  await assertOwnerAccessContext();
+  return mutateAdmission(
+    sid,
+    `/${encodeURIComponent(aid)}/revoke`,
+    ROUTES.revoke,
+    normalizedReason ? { reason: normalizedReason } : {},
+    {
+      targetPath,
+      idempotencyKey,
+      operationName: "session.admission_revoke",
+      origin,
+      resolveAuthSession,
+      requestMutation,
+    },
+  );
+}
+
+export async function setSessionAdmissionMode(
+  sessionId,
+  mode,
+  {
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const sid = required(sessionId, "session id");
+  const normalizedMode = normalizeString(mode).toLowerCase();
+  if (!["legacy", "required"].includes(normalizedMode)) {
+    throw new Error("mode must be legacy or required.");
+  }
+  await assertOwnerAccessContext();
+  const key = boundedIdempotencyKey(idempotencyKey, "session.admission_mode");
+  const auth = await authContext(targetPath, resolveAuthSession);
+  const result = await requestMutation(
+    `${auth.apiUrl}/api/v1/sessions/${encodeURIComponent(sid)}/admission-mode`,
+    {
+      method: "POST",
+      operationName: "session.admission_mode",
+      idempotencyKey: key,
+      headers: createSessionMutationHeaders({
+        bearerToken: auth.token,
+        sessionId: sid,
+        routeId: ROUTES.mode,
+        idempotencyKey: key,
+        origin,
+      }),
+      body: { mode: normalizedMode },
+    },
+  );
+  return { idempotencyKey: key, result };
+}

package/src/session/admission-auth.js

@@ -153,13 +153,20 @@ export const SESSION_AGENT_PRINCIPAL = Object.freeze({
   "ticket release": "actor",
   "ticket submit": "actor",
   "ticket events": "actor",
+  "access mode": "control",
+  "access request": "control",
+  "access list": "control",
+  "access status": "control",
+  "access approve": "control",
+  "access deny": "control",
+  "access revoke": "control",
   kill: "target",
   "stop-listener": "target",
   leave: "target",
   "guard-uninstall": "target",
   join: "control",
 });
-const SESSION_COMMAND_GROUPS = new Set(["checkpoint", "ticket"]);
+const SESSION_COMMAND_GROUPS = new Set(["access", "checkpoint", "ticket"]);
 
 async function implicitAgent(sessionId, targetPath, env) {
   // The same identity the command itself resolves when --agent is omitted

package/src/session/admission.js

@@ -63,7 +63,8 @@ const ROUTE = {
   claim: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/claim",
   cancel: "POST /api/v1/sessions/{session_id}/admissions/{admission_id}/cancel",
 };
-const TERMINAL = new Set(["denied", "cancelled", "expired", "revoked"]);
+// Final admission statuses: polling stops, nothing is claimed, local request state is cleared.
+const TERMINAL = new Set(["denied", "cancelled", "expired", "revoked", "stopped"]);
 const TTL_MIN_SECONDS = 300;
 const TTL_MAX_SECONDS = 86_400;
 
@@ -242,6 +243,34 @@ export function admissionCredentialPath(sessionId, agentId, { homeDir } = {}) {
   );
 }
 
+/**
+ * Whether this machine stores ANY agent admission credential (usable or not, any
+ * session): `<home>/.sentinelayer/agents/<agent>/admissions/<session>.json`. Agent keys
+ * alone do not count. An unreadable directory counts as present, never as absence.
+ */
+export async function hasStoredAdmissionCredentials({ homeDir } = {}) {
+  const agentsDir = path.join(sentinelayerHome(homeDir), "agents");
+  let agents;
+  try {
+    agents = await fsp.readdir(agentsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error && error.code === "ENOENT") return false;
+    return true;
+  }
+  for (const agent of agents) {
+    if (!agent.isDirectory()) continue;
+    let files;
+    try {
+      files = await fsp.readdir(path.join(agentsDir, agent.name, "admissions"));
+    } catch (error) {
+      if (error && error.code === "ENOENT") continue;
+      return true;
+    }
+    if (files.some((name) => name.endsWith(".json"))) return true;
+  }
+  return false;
+}
+
 /**
  * What this machine holds for (session, agent):
  *   { state: "none" }                        -- never admitted here: the legacy path applies
@@ -471,12 +500,39 @@ export async function runAdmissionJoin(
       headers: { Authorization: `Bearer ${auth.token}` },
     });
     state.status = polled.status;
-    if (polled.status === "approved" || TERMINAL.has(polled.status) || polled.status === "active") break;
-    onPending({ admissionId: state.admissionId, approveUrl: polled.approveUrl || state.approveUrl });
+    // Identity readiness is a server capability: a server that gates the claim on
+    // AIdenID identity evidence reports `identityReady` (true or false) on every
+    // approved poll. A server that does not report it issues the claim challenge on
+    // approval, so the claim proceeds as soon as the admission is approved.
+    const reportsIdentityReadiness =
+      polled.status === "approved" && Object.prototype.hasOwnProperty.call(polled, "identityReady");
+    const claimable =
+      polled.status === "approved" && (!reportsIdentityReadiness || polled.identityReady === true);
+    if (reportsIdentityReadiness) {
+      const claimReady = claimable && polled?.claim?.domain === CLAIM_DOMAIN && polled?.claim?.preimage;
+      if (polled.identityReady === true && !claimReady) {
+        throw new Error("Identity-ready admission did not include a valid claim challenge.");
+      }
+      if (polled.identityReady !== true && polled?.claim) {
+        throw new Error("Admission exposed a claim challenge before AIdenID identity evidence was ready.");
+      }
+    }
+    if (claimable || TERMINAL.has(polled.status) || polled.status === "active") break;
+    const phase = polled.status === "approved" ? "identity" : "approval";
+    onPending({
+      admissionId: state.admissionId,
+      approveUrl: polled.approveUrl || state.approveUrl,
+      phase,
+      identityReady: polled.identityReady === true,
+      identity: polled.identity || null,
+    });
     if (now() >= deadline) {
       await fsp.writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`);
       return {
-        status: "pending",
+        status: polled.status === "approved" ? "approved" : "pending",
+        phase,
+        identityReady: polled.identityReady === true,
+        identity: polled.identity || null,
         admissionId: state.admissionId,
         approveUrl: polled.approveUrl || state.approveUrl,
         waited: true,

package/src/session/control-events.js

@@ -14,6 +14,8 @@ const QUIET_SESSION_ACTION_TYPES = new Set([
   "dislike",
   "disregard",
   "like",
+  "undislike",
+  "unlike",
   "view",
 ]);