sentinelayer-cli 0.23.0 → 0.25.0

package/src/session/invitations.js

@@ -0,0 +1,241 @@
+import { createHmac, randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { renderCoordinationBulletList } from "./coordination-guidance.js";
+import { resolveSessionPaths } from "./paths.js";
+
+export const SESSION_INVITATION_ACCEPT_ROUTE_ID =
+  "POST /api/v1/sessions/{session_id}/invitations/accept";
+export const SESSION_MUTATION_ORIGIN = "https://sentinelayer.com";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function safeFileToken(value, fallback = "onboarding") {
+  const normalized = normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return (normalized || fallback).slice(0, 80);
+}
+
+export function canonicalSessionRef(value) {
+  const raw = normalizeString(value);
+  if (!raw) return "unavailable";
+  return raw.toLowerCase();
+}
+
+export function createSessionMutationCsrfToken({
+  bearerToken,
+  sessionId,
+  routeId,
+  idempotencyKey,
+} = {}) {
+  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");
+}
+
+export function createSessionMutationHeaders({
+  bearerToken,
+  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,
+    }),
+  };
+}
+
+export function createSessionMutationIdempotencyKey(operationName = "invitation-accept") {
+  const operation = normalizeString(operationName)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32) || "session-mutation";
+  return `sl-cli-${operation}-${randomUUID()}`;
+}
+
+export async function acceptSessionInvitation(
+  sessionId,
+  {
+    invitationToken,
+    seatKey = "",
+    agentId = "",
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedInvitationToken = normalizeString(invitationToken);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  if (!normalizedInvitationToken) {
+    throw new Error("invite token is required.");
+  }
+
+  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.");
+  }
+
+  const resolvedIdempotencyKey =
+    normalizeString(idempotencyKey) || createSessionMutationIdempotencyKey("session-invite-accept");
+  const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
+  const body = {
+    token: normalizedInvitationToken,
+  };
+  const normalizedSeatKey = normalizeString(seatKey);
+  const normalizedAgentId = normalizeString(agentId);
+  if (normalizedSeatKey) body.seatKey = normalizedSeatKey;
+  if (normalizedAgentId) body.agentId = normalizedAgentId;
+
+  const result = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
+    {
+      method: "POST",
+      operationName: "session.invitation_accept",
+      idempotencyKey: resolvedIdempotencyKey,
+      headers: createSessionMutationHeaders({
+        bearerToken: auth.token,
+        sessionId: normalizedSessionId,
+        routeId: SESSION_INVITATION_ACCEPT_ROUTE_ID,
+        idempotencyKey: resolvedIdempotencyKey,
+        origin,
+      }),
+      body,
+    },
+  );
+
+  return {
+    idempotencyKey: resolvedIdempotencyKey,
+    result,
+  };
+}
+
+export function normalizeSessionOnboarding(onboarding = {}, claimedSeat = null) {
+  const onboardingSource =
+    onboarding && typeof onboarding === "object" && !Array.isArray(onboarding) ? onboarding : {};
+  const seatSource =
+    claimedSeat && typeof claimedSeat === "object" && !Array.isArray(claimedSeat) ? claimedSeat : {};
+  const normalized = {
+    seatKey: normalizeString(onboardingSource.seatKey) || normalizeString(seatSource.seatKey) || null,
+    agentId:
+      normalizeString(onboardingSource.agentId) ||
+      normalizeString(seatSource.claimedAgentId) ||
+      normalizeString(seatSource.agentId) ||
+      null,
+    displayName:
+      normalizeString(onboardingSource.displayName) || normalizeString(seatSource.displayName) || null,
+    role: normalizeString(onboardingSource.role) || normalizeString(seatSource.role) || null,
+    instructions:
+      normalizeString(onboardingSource.instructions) || normalizeString(seatSource.instructions) || null,
+  };
+  return Object.values(normalized).some(Boolean) ? normalized : null;
+}
+
+function renderOnboardingMarkdown({ sessionId, onboarding, claimedSeat, agentId }) {
+  const lines = [
+    "# Senti Session Onboarding",
+    "",
+    `Session: ${sessionId}`,
+    `Agent: ${normalizeString(onboarding.agentId) || normalizeString(agentId) || "unknown"}`,
+  ];
+  if (onboarding.displayName) lines.push(`Display name: ${onboarding.displayName}`);
+  if (onboarding.role) lines.push(`Role: ${onboarding.role}`);
+  if (onboarding.seatKey) lines.push(`Seat key: ${onboarding.seatKey}`);
+  if (claimedSeat?.seatType) lines.push(`Seat type: ${normalizeString(claimedSeat.seatType)}`);
+  lines.push("", "## SOUL Instructions", "");
+  lines.push(onboarding.instructions || "No seat-specific instructions were provided.");
+  lines.push("", "## Session Etiquette", "", renderCoordinationBulletList());
+  lines.push(
+    "",
+    "## First Actions",
+    "",
+    `- Read recent room context: \`sl session read ${sessionId} --remote --tail 50 --json\``,
+    `- Start a quiet listener: \`sl session listen --session ${sessionId} --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence\``,
+    `- Post a short plan before editing: \`sl session say ${sessionId} \"plan: <scope>; files: <paths>\"\``,
+    "- Review `AGENTS.md` / `CLAUDE.md`, then keep `tasks/todo.md` current for work status.",
+    "- Add any Carter correction pattern to `tasks/lessons.md` before continuing the next slice.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeSessionOnboardingBrief(
+  sessionId,
+  {
+    onboarding,
+    claimedSeat = null,
+    agentId = "",
+    targetPath = process.cwd(),
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedOnboarding = normalizeSessionOnboarding(onboarding, claimedSeat);
+  if (!normalizedSessionId || !normalizedOnboarding) {
+    return null;
+  }
+  const paths = resolveSessionPaths(normalizedSessionId, { targetPath });
+  const owner = safeFileToken(normalizedOnboarding.agentId || agentId || normalizedOnboarding.seatKey);
+  const dir = path.join(paths.sentiDir, "onboarding");
+  const jsonPath = path.join(dir, `${owner}.json`);
+  const markdownPath = path.join(dir, `${owner}.md`);
+  const payload = {
+    schemaVersion: "1.0.0",
+    sessionId: normalizedSessionId,
+    agentId: normalizeString(agentId) || normalizedOnboarding.agentId || null,
+    onboarding: normalizedOnboarding,
+    claimedSeat: claimedSeat && typeof claimedSeat === "object" ? claimedSeat : null,
+    writtenAt: new Date().toISOString(),
+  };
+  await fsp.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fsp.writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8"),
+    fsp.writeFile(
+      markdownPath,
+      renderOnboardingMarkdown({
+        sessionId: normalizedSessionId,
+        onboarding: normalizedOnboarding,
+        claimedSeat,
+        agentId,
+      }),
+      "utf-8",
+    ),
+  ]);
+  return {
+    jsonPath,
+    markdownPath,
+    onboarding: normalizedOnboarding,
+  };
+}

package/src/session/listeners.js

@@ -0,0 +1,126 @@
+import { pollSessionEventsBefore } from "./sync.js";
+
+const LISTENER_EVENT_TYPES = new Set([
+  "session_listener_started",
+  "session_listener_heartbeat",
+  "session_listener_stopped",
+]);
+
+// A heartbeat older than this (and not explicitly stopped) means the
+// listener likely died without a clean stop — show it as stale, not live.
+const DEFAULT_STALE_AFTER_MS = 180_000;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function eventEpochMs(event) {
+  const raw = normalizeString(event?.ts) || normalizeString(event?.timestamp);
+  const parsed = Date.parse(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function readRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function positiveInt(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/**
+ * Reduce a stream of session_listener_* events into one row per agent: who is
+ * listening, at what cadence, and whether they're currently active or idle.
+ * Pure + testable — the command layer just fetches events and renders this.
+ */
+export function summarizeListeners(events = [], { nowMs = Date.now(), staleAfterMs = DEFAULT_STALE_AFTER_MS } = {}) {
+  const latestByAgent = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    const type = normalizeString(event?.event);
+    if (!LISTENER_EVENT_TYPES.has(type)) continue;
+    const agentId = normalizeString(event?.agent?.id) || normalizeString(readRecord(event?.payload).listenerId);
+    if (!agentId) continue;
+    const epoch = eventEpochMs(event) ?? 0;
+    const existing = latestByAgent.get(agentId);
+    if (!existing || epoch >= existing.epoch) {
+      latestByAgent.set(agentId, { event, type, epoch });
+    }
+  }
+
+  const rows = [];
+  for (const [agentId, { event, type, epoch }] of latestByAgent) {
+    const payload = readRecord(event.payload);
+    const ageMs = epoch ? Math.max(0, nowMs - epoch) : null;
+    const stopped = type === "session_listener_stopped";
+    const active = Boolean(payload.active);
+    const idleIntervalSeconds = positiveInt(payload.idleIntervalSeconds);
+    const activeIntervalSeconds = positiveInt(payload.activeIntervalSeconds);
+    const nextPollSeconds = positiveInt(payload.nextPollMs)
+      ? Math.round(positiveInt(payload.nextPollMs) / 1000)
+      : null;
+    // The effective cadence right now: active window uses the fast interval,
+    // otherwise the idle interval; fall back to the reported next poll.
+    const cadenceSeconds = active
+      ? activeIntervalSeconds || nextPollSeconds
+      : idleIntervalSeconds || nextPollSeconds;
+    let status;
+    if (stopped) status = "stopped";
+    else if (ageMs !== null && ageMs > staleAfterMs) status = "stale";
+    else status = active ? "active" : "idle";
+
+    rows.push({
+      agentId,
+      displayName: normalizeString(event.agent?.displayName) || agentId,
+      model: normalizeString(event.agent?.model),
+      status,
+      active,
+      cadenceSeconds: cadenceSeconds ?? null,
+      idleIntervalSeconds,
+      activeIntervalSeconds,
+      nextPollSeconds,
+      lastSeenAt: epoch ? new Date(epoch).toISOString() : null,
+      lastSeenAgoSeconds: ageMs !== null ? Math.round(ageMs / 1000) : null,
+      lastHumanActivityAt: normalizeString(payload.lastHumanActivityAt) || null,
+    });
+  }
+
+  // Live listeners first, then by most-recently-seen.
+  const statusRank = { active: 0, idle: 1, stale: 2, stopped: 3 };
+  rows.sort((a, b) => {
+    const r = (statusRank[a.status] ?? 9) - (statusRank[b.status] ?? 9);
+    if (r !== 0) return r;
+    return (b.lastSeenAt || "").localeCompare(a.lastSeenAt || "");
+  });
+  return rows;
+}
+
+/**
+ * Fetch recent session events from the API and summarize the listeners.
+ * `limit` controls how far back we look for heartbeats.
+ */
+export async function fetchSessionListeners(
+  sessionId,
+  { targetPath = process.cwd(), limit = 200, nowMs = Date.now, poll = pollSessionEventsBefore } = {}
+) {
+  const result = await poll(sessionId, { targetPath, limit });
+  if (!result?.ok) {
+    return { ok: false, reason: normalizeString(result?.reason) || "fetch_failed", listeners: [] };
+  }
+  const listeners = summarizeListeners(result.events || [], { nowMs: nowMs() });
+  return { ok: true, sessionId: normalizeString(sessionId), listeners };
+}
+
+export function formatListenerLine(row) {
+  const cadence = row.cadenceSeconds ? `${row.cadenceSeconds}s` : "—";
+  const seen = row.lastSeenAgoSeconds === null ? "never" : `${row.lastSeenAgoSeconds}s ago`;
+  const statusLabel =
+    row.status === "active"
+      ? "● active"
+      : row.status === "idle"
+        ? "○ idle"
+        : row.status === "stale"
+          ? "◌ stale"
+          : "× stopped";
+  return `${statusLabel.padEnd(10)} ${row.agentId.padEnd(24)} cadence=${cadence.padEnd(6)} last_seen=${seen}`;
+}

package/src/session/stream.js

@@ -15,6 +15,10 @@ 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;
+const METADATA_WRITE_RETRY_ATTEMPTS = 5;
+const METADATA_WRITE_RETRY_DELAY_MS = 50;
+
+let metadataWriteCounter = 0;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -68,11 +72,36 @@ async function readSessionMetadata(paths) {
   }
 }
 
+function isRetryableMetadataWriteError(error) {
+  const code = error && typeof error === "object" ? error.code : "";
+  return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+
+async function replaceMetadataFile(tmpPath, metadataPath) {
+  for (let attempt = 1; attempt <= METADATA_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      await fsp.rename(tmpPath, metadataPath);
+      return;
+    } catch (error) {
+      if (!isRetryableMetadataWriteError(error) || attempt >= METADATA_WRITE_RETRY_ATTEMPTS) {
+        throw error;
+      }
+      await sleep(METADATA_WRITE_RETRY_DELAY_MS * attempt);
+    }
+  }
+}
+
 async function writeSessionMetadata(paths, metadata = {}) {
   await fsp.mkdir(paths.sessionDir, { recursive: true });
-  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.tmp`;
+  metadataWriteCounter = (metadataWriteCounter + 1) % Number.MAX_SAFE_INTEGER;
+  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.${metadataWriteCounter}.tmp`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
-  await fsp.rename(tmpPath, paths.metadataPath);
+  try {
+    await replaceMetadataFile(tmpPath, paths.metadataPath);
+  } catch (error) {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 function remoteStatusAllowsLocalRefresh(remoteSession = {}) {

package/src/session/wake/listen-wake.js

@@ -0,0 +1,144 @@
+import { createResolveTarget } from "./resolve-target.js";
+import claudeWakeAdapter from "./claude.js";
+import codexWakeAdapter from "./codex.js";
+
+const BUILTIN_ADAPTERS = {
+  claude: claudeWakeAdapter,
+  codex: codexWakeAdapter,
+};
+
+// Receipt-confirmation defaults (Carter's idea: a wake isn't done until the
+// agent actually acks/views the message). Conservative so reconcile never
+// spam-resumes a slow-but-awake agent.
+const DEFAULT_CONFIRM_WINDOW_MS = 90_000;
+const DEFAULT_MAX_WAKE_ATTEMPTS = 3;
+const RECEIPT_ACTION_TYPES = new Set(["ack", "view", "reply", "working_on", "like"]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function eventSequence(event) {
+  const raw = event?.sequenceId ?? event?.sequence_id ?? event?.payload?.sequenceId;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+/**
+ * Wire the built wake bus (resolve-target routing + a host adapter) into the
+ * live `sl session listen` poll so an addressed message INSTANTLY resumes the
+ * host — the auto-wake cutover — and CONFIRMS the wake via read receipts.
+ *
+ * Returns { trigger, reconcile, pendingCount } or null when disabled:
+ *  - trigger(event): route + resume the host on an addressed message, and (if
+ *    the message has a durable sequence) record a pending wake to confirm.
+ *  - reconcile({ fetchActions, nowMs }): for each pending wake, fetch the
+ *    message's actions; if THIS agent acked/viewed/replied → confirmed (woke).
+ *    Else past the confirm window, re-resume (up to maxAttempts) — the agent
+ *    didn't wake. Past maxAttempts → dead-letter. Never throws.
+ */
+export function createListenerHostWake({
+  host,
+  resumeSessionId,
+  agentId,
+  sessionId,
+  adapters = BUILTIN_ADAPTERS,
+  confirmWindowMs = DEFAULT_CONFIRM_WINDOW_MS,
+  maxAttempts = DEFAULT_MAX_WAKE_ATTEMPTS,
+} = {}) {
+  const hostName = normalizeString(host).toLowerCase();
+  const resumeId = normalizeString(resumeSessionId);
+  const selfId = normalizeString(agentId);
+  const sid = normalizeString(sessionId);
+  const adapter = adapters[hostName];
+  if (!adapter || typeof adapter.wake !== "function") return null;
+  if (!resumeId || !selfId || !sid) return null;
+
+  const resolveTarget = createResolveTarget({
+    agentId: selfId,
+    host: hostName,
+    sessionId: resumeId,
+  });
+
+  // Serialize resumes: each spawns a host process; never two at once.
+  let queue = Promise.resolve();
+  // seq -> { target, attempts, lastWakeAt }
+  const pending = new Map();
+
+  function resume(target) {
+    queue = queue.then(async () => {
+      try {
+        const result = await adapter.wake(target);
+        return {
+          woken: Boolean(result?.ok),
+          ok: Boolean(result?.ok),
+          reason: result?.ok ? "resumed" : normalizeString(result?.reason) || "wake_failed",
+          host: hostName,
+        };
+      } catch (error) {
+        return { woken: false, ok: false, reason: normalizeString(error?.message) || "wake_error", host: hostName };
+      }
+    });
+    return queue;
+  }
+
+  function trigger(event) {
+    const target = resolveTarget(event);
+    if (!target) return Promise.resolve({ woken: false, reason: "not_routed" });
+    const seq = eventSequence(event);
+    // Record a pending wake to confirm. lastWakeAt is stamped on the first
+    // reconcile (callers own the clock) so the confirm window starts then.
+    if (seq !== null && !pending.has(seq)) {
+      pending.set(seq, { target, attempts: 1, lastWakeAt: Number.NaN });
+    }
+    return resume(target);
+  }
+
+  async function reconcile({ fetchActions, nowMs = 0 } = {}) {
+    const summary = { confirmed: 0, retried: 0, deadLettered: 0, stillPending: 0 };
+    if (typeof fetchActions !== "function" || pending.size === 0) {
+      summary.stillPending = pending.size;
+      return summary;
+    }
+    for (const [seq, entry] of [...pending.entries()]) {
+      if (!Number.isFinite(entry.lastWakeAt)) entry.lastWakeAt = nowMs;
+      let actions = [];
+      try {
+        const res = await fetchActions(seq);
+        actions = Array.isArray(res?.actions) ? res.actions : [];
+      } catch {
+        // transient fetch error — leave pending, try next reconcile
+        summary.stillPending += 1;
+        continue;
+      }
+      const acked = actions.some(
+        (a) =>
+          normalizeString(a?.actorId).toLowerCase() === selfId.toLowerCase() &&
+          RECEIPT_ACTION_TYPES.has(normalizeString(a?.actionType).toLowerCase()),
+      );
+      if (acked) {
+        pending.delete(seq);
+        summary.confirmed += 1;
+        continue;
+      }
+      if (nowMs - entry.lastWakeAt >= confirmWindowMs) {
+        if (entry.attempts < maxAttempts) {
+          entry.attempts += 1;
+          entry.lastWakeAt = nowMs;
+          void resume(entry.target);
+          summary.retried += 1;
+        } else {
+          pending.delete(seq);
+          summary.deadLettered += 1;
+        }
+      } else {
+        summary.stillPending += 1;
+      }
+    }
+    return summary;
+  }
+
+  return { trigger, reconcile, pendingCount: () => pending.size };
+}
+
+export { BUILTIN_ADAPTERS };