sentinelayer-cli 0.9.5 → 0.9.6

package/package.json

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

package/src/commands/session.js

@@ -77,6 +77,11 @@ import {
   getTemplateRegistry,
   resolveSessionTemplate,
 } from "../session/templates.js";
+import {
+  createSessionCheckpoint,
+  generateSessionCheckpoint,
+  listSessionCheckpoints,
+} from "../session/checkpoints.js";
 import { authLoginHint } from "../ui/command-hints.js";
 import { parseCsvTokens } from "./ai/shared.js";
 
@@ -561,6 +566,53 @@ function formatEventLine(event = {}) {
   return `${ts} ${agentId} ${type}`;
 }
 
+function checkpointSequenceRange(checkpoint = {}) {
+  const start = Number(checkpoint.startSequence || 0);
+  const end = Number(checkpoint.endSequence || 0);
+  if (Number.isFinite(start) && start > 0 && Number.isFinite(end) && end > 0) {
+    return `#${Math.floor(start)}-${Math.floor(end)}`;
+  }
+  if (Number.isFinite(start) && start > 0) {
+    return `#${Math.floor(start)}`;
+  }
+  return "anchor pending";
+}
+
+function formatCheckpointLine(checkpoint = {}) {
+  const id = normalizeString(checkpoint.checkpointId) || "checkpoint";
+  const kind = normalizeString(checkpoint.kind) || "summary";
+  const title = normalizeString(checkpoint.title) || "Untitled checkpoint";
+  const byline = normalizeString(checkpoint.createdByAgentId || checkpoint.createdBy);
+  const by = byline ? ` by ${byline}` : "";
+  return `${checkpointSequenceRange(checkpoint)} ${id} [${kind}] ${title}${by}`;
+}
+
+async function readCheckpointSummaryOption(options = {}, { targetPath } = {}) {
+  const inlineSummary = normalizeString(options.summary);
+  const summaryFile = normalizeString(options.summaryFile);
+  if (inlineSummary && summaryFile) {
+    throw new Error("Use either --summary or --summary-file, not both.");
+  }
+  if (summaryFile) {
+    const resolved = path.resolve(targetPath || process.cwd(), summaryFile);
+    return fsp.readFile(resolved, "utf-8");
+  }
+  return inlineSummary;
+}
+
+async function hydrateAfterCheckpointMutation(sessionId, { targetPath } = {}) {
+  return hydrateSessionFromRemote({
+    sessionId,
+    targetPath,
+    probeOpenCircuit: false,
+    eventPageLimit: 200,
+    maxEventPages: 5,
+  }).catch((error) => ({
+    ok: false,
+    reason: error instanceof Error ? error.message : "hydrate_failed",
+  }));
+}
+
 async function appendMissingRemoteEvents(sessionId, remoteEvents = [], { targetPath } = {}) {
   const events = Array.isArray(remoteEvents) ? remoteEvents : [];
   if (events.length === 0) {
@@ -1884,6 +1936,155 @@ export function registerSessionCommand(program) {
       }
     });
 
+  const checkpoint = session
+    .command("checkpoint")
+    .description("List, create, and generate durable session checkpoints");
+
+  checkpoint
+    .command("list <sessionId>")
+    .description("List durable checkpoints for a remote session")
+    .option("--limit <n>", "Maximum checkpoints to return (default 100, max 200)", "100")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const result = await listSessionCheckpoints(normalizedSessionId, {
+        targetPath,
+        limit: options.limit,
+      });
+      const payload = {
+        command: "session checkpoint list",
+        targetPath,
+        ...result,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.checkpoints.length === 0) {
+        console.log(pc.gray(`No checkpoints for session ${normalizedSessionId}.`));
+        return;
+      }
+      for (const item of result.checkpoints) {
+        console.log(formatCheckpointLine(item));
+      }
+    });
+
+  checkpoint
+    .command("create <sessionId>")
+    .description("Create a durable checkpoint anchored to a canonical sequence range")
+    .requiredOption("--start-sequence <n>", "First canonical event sequence included in the checkpoint")
+    .requiredOption("--end-sequence <n>", "Last canonical event sequence included in the checkpoint")
+    .requiredOption("--title <title>", "Short checkpoint title")
+    .option("--summary <text>", "Checkpoint summary text")
+    .option("--summary-file <file>", "Read checkpoint summary text from a file")
+    .option("--kind <kind>", "Checkpoint kind (summary, handoff, milestone, billing)", "summary")
+    .option("--checkpoint-id <id>", "Explicit checkpoint id; defaults to a stable hash of range/body")
+    .option("--agent <id>", "Optional agent id recorded as checkpoint creator")
+    .option("--token-start <n>", "Optional token-range start")
+    .option("--token-end <n>", "Optional token-range end")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeString(options.agent)
+        ? await defaultAgentId(options.agent, targetPath)
+        : "";
+      const summary = await readCheckpointSummaryOption(options, { targetPath });
+      const result = await createSessionCheckpoint(normalizedSessionId, {
+        targetPath,
+        checkpointId: options.checkpointId,
+        startSequence: options.startSequence,
+        endSequence: options.endSequence,
+        kind: options.kind,
+        title: options.title,
+        summary,
+        createdByAgentId: agentId,
+        tokenStart: options.tokenStart,
+        tokenEnd: options.tokenEnd,
+      });
+      const hydration = await hydrateAfterCheckpointMutation(normalizedSessionId, { targetPath });
+      const payload = {
+        command: "session checkpoint create",
+        targetPath,
+        ...result,
+        hydration,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      const duplicate = result.duplicate ? "duplicate " : "";
+      console.log(pc.bold(`${duplicate}checkpoint created`));
+      if (result.checkpoint) {
+        console.log(formatCheckpointLine(result.checkpoint));
+      }
+      if (!hydration.ok) {
+        console.log(pc.gray(`Local hydrate skipped: ${hydration.reason || "unknown"}`));
+      }
+    });
+
+  checkpoint
+    .command("generate <sessionId>")
+    .description("Generate a checkpoint from the next uncheckpointed durable event window")
+    .option("--min-events <n>", "Minimum source events required before creating (default 20)", "20")
+    .option("--max-events <n>", "Maximum source events to summarize (default 80, max 200)", "80")
+    .option("--operation-id <key>", "Explicit retry key for this generate invocation")
+    .option("--agent <id>", "Optional agent id recorded as checkpoint creator")
+    .option("--path <path>", "Workspace path for auth/session context", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeString(options.agent)
+        ? await defaultAgentId(options.agent, targetPath)
+        : "";
+      const result = await generateSessionCheckpoint(normalizedSessionId, {
+        targetPath,
+        minEvents: options.minEvents,
+        maxEvents: options.maxEvents,
+        idempotencyKey: options.operationId,
+        createdByAgentId: agentId,
+      });
+      const hydration = result.checkpoint
+        ? await hydrateAfterCheckpointMutation(normalizedSessionId, { targetPath })
+        : null;
+      const payload = {
+        command: "session checkpoint generate",
+        targetPath,
+        ...result,
+        hydration: hydration || undefined,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (result.checkpoint) {
+        console.log(pc.bold(result.duplicate ? "checkpoint already covered" : "checkpoint generated"));
+        console.log(formatCheckpointLine(result.checkpoint));
+        if (hydration && !hydration.ok) {
+          console.log(pc.gray(`Local hydrate skipped: ${hydration.reason || "unknown"}`));
+        }
+        return;
+      }
+      console.log(
+        pc.gray(
+          `No checkpoint created: ${normalizeString(result.reason) || "not_needed"} (${Number(result.eventCount || 0)} events, min ${Number(result.minEvents || 0)}).`,
+        ),
+      );
+    });
+
   session
     .command("status <sessionId>")
     .description("Show session status, agents, and health")

package/src/session/checkpoints.js

@@ -0,0 +1,294 @@
+import crypto from "node:crypto";
+import process from "node:process";
+
+import { requestJson, requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+
+const DEFAULT_API_BASE_URL = "https://api.sentinelayer.com";
+const DEFAULT_CHECKPOINT_LIMIT = 100;
+const MAX_CHECKPOINT_LIMIT = 200;
+const DEFAULT_MIN_EVENTS = 20;
+const DEFAULT_MAX_EVENTS = 80;
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeApiUrl(value) {
+  return (normalizeString(value) || DEFAULT_API_BASE_URL).replace(/\/+$/g, "");
+}
+
+function parsePositiveInteger(value, field, fallbackValue = null) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    if (fallbackValue !== null) return fallbackValue;
+    throw new Error(`${field} is required.`);
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeLimit(value) {
+  const parsed = parsePositiveInteger(value, "limit", DEFAULT_CHECKPOINT_LIMIT);
+  return Math.max(1, Math.min(MAX_CHECKPOINT_LIMIT, parsed));
+}
+
+function stableHash(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(stableJson(value)))
+    .digest("hex");
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => stableJson(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    const next = stableJson(value[key]);
+    if (next !== undefined && next !== null && next !== "") {
+      out[key] = next;
+    }
+  }
+  return out;
+}
+
+function buildCheckpointFingerprint(payload) {
+  return stableHash(stableJson(payload));
+}
+
+function buildStableCheckpointId(sessionId, payload) {
+  const fingerprint = buildCheckpointFingerprint({
+    sessionId: normalizeString(sessionId),
+    startSequence: payload.startSequence,
+    endSequence: payload.endSequence,
+    kind: payload.kind,
+    title: payload.title,
+    summary: payload.summary,
+    createdByAgentId: payload.createdByAgentId,
+    tokenRange: payload.tokenRange || null,
+  });
+  return `cp_cli_${fingerprint.slice(0, 24)}`;
+}
+
+function buildStableIdempotencyKey(sessionId, operation, payload) {
+  const fingerprint = buildCheckpointFingerprint({
+    sessionId: normalizeString(sessionId),
+    operation,
+    payload,
+  });
+  return `sl_cli_session_checkpoint_${fingerprint}`;
+}
+
+function buildInvocationIdempotencyKey(operation) {
+  let suffix;
+  try {
+    suffix = crypto.randomUUID();
+  } catch {
+    suffix = crypto.randomBytes(16).toString("hex");
+  }
+  return `sl_cli_session_checkpoint_${normalizeString(operation) || "mutation"}_${suffix}`;
+}
+
+function normalizeTokenRange({ tokenStart, tokenEnd } = {}) {
+  const hasStart = tokenStart !== undefined && normalizeString(tokenStart) !== "";
+  const hasEnd = tokenEnd !== undefined && normalizeString(tokenEnd) !== "";
+  if (!hasStart && !hasEnd) return null;
+  const start = hasStart ? parsePositiveInteger(tokenStart, "token-start") : null;
+  const end = hasEnd ? parsePositiveInteger(tokenEnd, "token-end") : null;
+  if (start !== null && end !== null && start > end) {
+    throw new Error("token-start must be less than or equal to token-end.");
+  }
+  return { start, end };
+}
+
+export function buildManualCheckpointPayload(sessionId, {
+  checkpointId = "",
+  startSequence,
+  endSequence,
+  kind = "summary",
+  title,
+  summary,
+  createdByAgentId = "",
+  tokenStart,
+  tokenEnd,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedStart = parsePositiveInteger(startSequence, "start-sequence");
+  const normalizedEnd = parsePositiveInteger(endSequence, "end-sequence");
+  if (normalizedStart > normalizedEnd) {
+    throw new Error("start-sequence must be less than or equal to end-sequence.");
+  }
+  const normalizedTitle = normalizeString(title);
+  if (!normalizedTitle) {
+    throw new Error("title is required.");
+  }
+  const normalizedSummary = normalizeString(summary);
+  if (!normalizedSummary) {
+    throw new Error("summary is required.");
+  }
+  const normalizedKind = normalizeString(kind) || "summary";
+  const normalizedCreatedBy = normalizeString(createdByAgentId);
+  const tokenRange = normalizeTokenRange({ tokenStart, tokenEnd });
+  const body = {
+    startSequence: normalizedStart,
+    endSequence: normalizedEnd,
+    kind: normalizedKind,
+    title: normalizedTitle,
+    summary: normalizedSummary,
+  };
+  if (normalizedCreatedBy) {
+    body.createdByAgentId = normalizedCreatedBy;
+  }
+  if (tokenRange) {
+    body.tokenRange = tokenRange;
+  }
+  body.checkpointId = normalizeString(checkpointId) || buildStableCheckpointId(normalizedSessionId, body);
+  return {
+    body,
+    idempotencyKey: buildStableIdempotencyKey(normalizedSessionId, "create", body),
+  };
+}
+
+export function buildGenerateCheckpointPayload(sessionId, {
+  minEvents = DEFAULT_MIN_EVENTS,
+  maxEvents = DEFAULT_MAX_EVENTS,
+  createdByAgentId = "",
+  idempotencyKey = "",
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const normalizedMin = parsePositiveInteger(minEvents, "min-events", DEFAULT_MIN_EVENTS);
+  const normalizedMax = parsePositiveInteger(maxEvents, "max-events", DEFAULT_MAX_EVENTS);
+  if (normalizedMin > 200) {
+    throw new Error("min-events must be less than or equal to 200.");
+  }
+  if (normalizedMax > 200) {
+    throw new Error("max-events must be less than or equal to 200.");
+  }
+  if (normalizedMax < normalizedMin) {
+    throw new Error("max-events must be greater than or equal to min-events.");
+  }
+  const body = {
+    minEvents: normalizedMin,
+    maxEvents: normalizedMax,
+  };
+  const normalizedCreatedBy = normalizeString(createdByAgentId);
+  if (normalizedCreatedBy) {
+    body.createdByAgentId = normalizedCreatedBy;
+  }
+  return {
+    body,
+    idempotencyKey:
+      normalizeString(idempotencyKey) || buildInvocationIdempotencyKey("generate"),
+  };
+}
+
+async function resolveCheckpointApi({
+  targetPath = process.cwd(),
+  resolveAuthSession = resolveActiveAuthSession,
+} = {}) {
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth || !auth.token) {
+    throw new Error("Sentinelayer auth is required. Run `sl auth login` first.");
+  }
+  return {
+    apiUrl: normalizeApiUrl(auth.apiUrl),
+    headers: { Authorization: `Bearer ${auth.token}` },
+  };
+}
+
+export async function listSessionCheckpoints(sessionId, {
+  targetPath = process.cwd(),
+  limit = DEFAULT_CHECKPOINT_LIMIT,
+  resolveAuthSession = resolveActiveAuthSession,
+  request = requestJson,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const params = new URLSearchParams({ limit: String(normalizeLimit(limit)) });
+  const response = await request(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints?${params.toString()}`,
+    { method: "GET", headers },
+  );
+  const checkpoints = Array.isArray(response?.checkpoints) ? response.checkpoints : [];
+  return {
+    ok: true,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoints,
+    count: Number(response?.count ?? checkpoints.length) || checkpoints.length,
+  };
+}
+
+export async function createSessionCheckpoint(sessionId, options = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = options;
+  const { body, idempotencyKey } = buildManualCheckpointPayload(normalizedSessionId, options);
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints`,
+    {
+      operationName: "session-checkpoint-create",
+      headers,
+      body,
+      idempotencyKey,
+    },
+  );
+  return {
+    ...response,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoint: response?.checkpoint || null,
+    idempotencyKey,
+  };
+}
+
+export async function generateSessionCheckpoint(sessionId, options = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = options;
+  const { body, idempotencyKey } = buildGenerateCheckpointPayload(normalizedSessionId, options);
+  const { apiUrl, headers } = await resolveCheckpointApi({ targetPath, resolveAuthSession });
+  const response = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/checkpoints/generate`,
+    {
+      operationName: "session-checkpoint-generate",
+      headers,
+      body,
+      idempotencyKey,
+    },
+  );
+  return {
+    ...response,
+    sessionId: normalizedSessionId,
+    apiUrl,
+    checkpoint: response?.checkpoint || null,
+    idempotencyKey,
+  };
+}