sentinelayer-cli 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.9.4",
+  "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

@@ -68,6 +68,7 @@ import {
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
+import { buildSessionRecap } from "../session/recap.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
 import { pushSessionTitleToApi } from "../session/title-sync.js";
 import {
@@ -76,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";
 
@@ -560,6 +566,98 @@ 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) {
+    return {
+      appended: 0,
+      skipped: 0,
+      failed: 0,
+    };
+  }
+  const knownKeys = new Set();
+  const localEvents = await readStream(sessionId, {
+    targetPath,
+    tail: 0,
+  });
+  for (const event of localEvents) {
+    addSessionEventIdentityKeys(knownKeys, event);
+  }
+
+  let appended = 0;
+  let skipped = 0;
+  let failed = 0;
+  for (const event of events) {
+    if (sessionEventHasKnownIdentity(event, knownKeys)) {
+      skipped += 1;
+      continue;
+    }
+    try {
+      const persisted = await appendToStream(sessionId, event, {
+        targetPath,
+        syncRemote: false,
+      });
+      addSessionEventIdentityKeys(knownKeys, persisted);
+      appended += 1;
+    } catch {
+      addSessionEventIdentityKeys(knownKeys, event);
+      failed += 1;
+    }
+  }
+  return {
+    appended,
+    skipped,
+    failed,
+  };
+}
+
 function formatTemplateLaunchLine(slot = {}) {
   const terminal = Number(slot.terminal || 0);
   const role = normalizeString(slot.role) || "agent";
@@ -1479,6 +1577,92 @@ export function registerSessionCommand(program) {
       }
     });
 
+  const recap = session
+    .command("recap")
+    .description("Build deterministic Senti session recaps");
+
+  recap
+    .command("now [sessionId]")
+    .description("Summarize current session activity, peers, findings, locks, and task ownership")
+    .option("--session <id>", "Session id to recap")
+    .option(
+      "--remote",
+      "Hydrate the latest durable API events before building the recap",
+    )
+    .option(
+      "--agent <id>",
+      "Agent id requesting the recap; self-authored events are omitted from recent snippets",
+      process.env.SENTINELAYER_AGENT_ID || "",
+    )
+    .option("--max-events <n>", "Maximum recent local events to inspect (default 100)", "100")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId) || resolveSessionIdOption(options);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "");
+      const maxEvents = parsePositiveInteger(options.maxEvents, "max-events", 100);
+      let hydration = null;
+      let remoteTail = null;
+      let remoteAppend = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        });
+        remoteTail = await pollSessionEventsBefore(normalizedSessionId, {
+          targetPath,
+          limit: maxEvents,
+          timeoutMs: 15_000,
+        });
+        if (remoteTail?.ok && Array.isArray(remoteTail.events) && remoteTail.events.length > 0) {
+          remoteAppend = await appendMissingRemoteEvents(normalizedSessionId, remoteTail.events, {
+            targetPath,
+          });
+        }
+      }
+      const current = await buildSessionRecap(normalizedSessionId, {
+        forAgentId: agentId,
+        maxEvents,
+        targetPath,
+      });
+      const payload = {
+        command: "session recap now",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId: current.forAgentId,
+        maxEvents,
+        generatedAt: current.generatedAt,
+        ephemeral: current.ephemeral,
+        style: current.style,
+        recap: current.text,
+        summary: current.summary,
+        remote: options.remote
+          ? {
+              hydration,
+              tailProbe: remoteTail
+                ? {
+                    ok: Boolean(remoteTail.ok),
+                    reason: remoteTail.reason || "",
+                    count: Array.isArray(remoteTail.events) ? remoteTail.events.length : 0,
+                    cursor: remoteTail.cursor || null,
+                  }
+                : null,
+              appendedTail: remoteAppend,
+            }
+          : null,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Recap for session ${normalizedSessionId}`));
+      if (payload.agentId) {
+        console.log(pc.gray(`for agent=${payload.agentId}`));
+      }
+      console.log(current.text);
+    });
+
   session
     .command("read <sessionId>")
     .description("Read recent session messages")
@@ -1752,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,
+  };
+}

package/src/session/recap.js

@@ -3,8 +3,10 @@ import path from "node:path";
 import process from "node:process";
 
 import { createAgentEvent } from "../events/schema.js";
+import { dedupeSessionEvents } from "./event-identity.js";
 import { resolveSessionPaths } from "./paths.js";
 import { appendToStream, readStream } from "./stream.js";
+import { getSession } from "./store.js";
 
 const SENTI_AGENT_ID = "senti";
 const SENTI_MODEL = "gpt-5.4-mini";
@@ -279,11 +281,12 @@ async function readTaskLedgerSummary(
   }
 }
 
-function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
-  if (!Array.isArray(events) || events.length === 0) {
+function elapsedMinutesBetween(startIso, nowIso = new Date().toISOString()) {
+  const normalizedStartIso = normalizeString(startIso);
+  if (!normalizedStartIso) {
     return 0;
   }
-  const firstEpoch = toEpoch(events[0]?.ts, nowIso);
+  const firstEpoch = toEpoch(normalizedStartIso, nowIso);
   const nowEpoch = toEpoch(nowIso, nowIso);
   if (!Number.isFinite(firstEpoch) || !Number.isFinite(nowEpoch) || nowEpoch <= firstEpoch) {
     return 0;
@@ -291,6 +294,51 @@ function buildElapsedMinutes(events = [], nowIso = new Date().toISOString()) {
   return Math.max(0, Math.floor((nowEpoch - firstEpoch) / 60_000));
 }
 
+function earliestIso(values = [], fallbackIso = new Date().toISOString()) {
+  const validEpochs = values
+    .map((value) => normalizeString(value))
+    .filter(Boolean)
+    .map((value) => Date.parse(value))
+    .filter((value) => Number.isFinite(value));
+  if (validEpochs.length === 0) {
+    return "";
+  }
+  validEpochs.sort((left, right) => left - right);
+  return normalizeIsoTimestamp(new Date(validEpochs[0]).toISOString(), fallbackIso);
+}
+
+function buildElapsedMinutes(events = [], nowIso = new Date().toISOString(), { startedAt = "" } = {}) {
+  const eventStart = Array.isArray(events) && events.length > 0 ? events[0]?.ts || events[0]?.timestamp : "";
+  const startIso = earliestIso([startedAt, eventStart], nowIso);
+  return elapsedMinutesBetween(startIso, nowIso);
+}
+
+function eventSequenceNumber(event = {}) {
+  for (const value of [event.sequenceId, event.sequence, event.seq, event.payload?.sequenceId]) {
+    const normalized = Number(value);
+    if (Number.isFinite(normalized)) {
+      return normalized;
+    }
+  }
+  return 0;
+}
+
+function sortEventsByConversationTime(events = [], fallbackIso = new Date().toISOString()) {
+  return [...(Array.isArray(events) ? events : [])].sort((left, right) => {
+    const leftEpoch = toEpoch(left?.ts || left?.timestamp, fallbackIso);
+    const rightEpoch = toEpoch(right?.ts || right?.timestamp, fallbackIso);
+    if (leftEpoch !== rightEpoch) {
+      return leftEpoch - rightEpoch;
+    }
+    const leftSequence = eventSequenceNumber(left);
+    const rightSequence = eventSequenceNumber(right);
+    if (leftSequence !== rightSequence) {
+      return leftSequence - rightSequence;
+    }
+    return normalizeString(left?.cursor).localeCompare(normalizeString(right?.cursor));
+  });
+}
+
 function buildRecapKey(sessionId, targetPath) {
   return `${path.resolve(String(targetPath || "."))}::${normalizeString(sessionId)}`;
 }
@@ -413,10 +461,19 @@ export async function buildSessionRecap(
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_RECAP_MAX_EVENTS);
   const normalizedForAgentId = normalizeString(forAgentId);
 
-  const events = await readStream(normalizedSessionId, {
+  const allEvents = await readStream(normalizedSessionId, {
     targetPath: normalizedTargetPath,
-    tail: normalizedMaxEvents,
+    tail: 0,
   });
+  let sessionMetadata = null;
+  try {
+    sessionMetadata = await getSession(normalizedSessionId, { targetPath: normalizedTargetPath });
+  } catch {
+    sessionMetadata = null;
+  }
+  const events = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow).slice(
+    -normalizedMaxEvents,
+  );
   const visibleEvents = (Array.isArray(events) ? events : []).filter((event) => {
     const agentId = normalizeString(event.agent?.id || event.agentId);
     if (!agentId) {
@@ -452,7 +509,10 @@ export async function buildSessionRecap(
     forAgentId: normalizedForAgentId,
     limit: 2,
   });
-  const elapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow);
+  const windowElapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow);
+  const elapsedMinutes = buildElapsedMinutes(visibleEvents, normalizedNow, {
+    startedAt: sessionMetadata?.createdAt,
+  });
   const latestEvent = visibleEvents.length > 0 ? visibleEvents[visibleEvents.length - 1] : null;
   const recapText = buildRecapText({
     activeAgents,
@@ -481,6 +541,10 @@ export async function buildSessionRecap(
       taskLedger,
       snippets,
       elapsedMinutes,
+      windowElapsedMinutes,
+      sessionStartedAt: sessionMetadata?.createdAt
+        ? normalizeIsoTimestamp(sessionMetadata.createdAt, normalizedNow)
+        : null,
       lastActorId: normalizeString(latestEvent?.agent?.id || latestEvent?.agentId) || null,
       lastEventAt: latestEvent ? normalizeIsoTimestamp(latestEvent.ts, normalizedNow) : null,
     },