sentinelayer-cli 0.8.0 → 0.8.1

package/src/session/store.js

@@ -3,7 +3,9 @@ import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 
+import { buildArtifactLineageIndex, verifyArtifactChain } from "../daemon/artifact-lineage.js";
 import { collectCodebaseIngest } from "../ingest/engine.js";
+import { computeSessionAnalytics } from "./analytics.js";
 import { resolveSessionPaths, resolveSessionsRoot } from "./paths.js";
 import { appendToStream } from "./stream.js";
 
@@ -30,6 +32,17 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function normalizeNonNegativeInteger(value, fallbackValue = 0) {
+  if (value === undefined || value === null || normalizeString(value) === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized < 0) {
+    return fallbackValue;
+  }
+  return Math.floor(normalized);
+}
+
 function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
   const normalized = normalizeString(value);
   if (!normalized) {
@@ -109,6 +122,90 @@ function normalizeCodebaseContext(ingest = {}) {
   };
 }
 
+function normalizeStringList(values = []) {
+  if (!Array.isArray(values)) {
+    return [];
+  }
+  return Array.from(
+    new Set(
+      values
+        .map((value) => normalizeString(value))
+        .filter(Boolean)
+    )
+  );
+}
+
+function toPosixPath(value = "") {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function toRelativePosix(baseDir, absolutePath) {
+  if (!absolutePath) {
+    return "";
+  }
+  return toPosixPath(path.relative(baseDir, absolutePath));
+}
+
+function normalizeDateKeyFromCloseoutPath(closeoutPath = "", fallbackIso = new Date().toISOString()) {
+  const normalized = toPosixPath(closeoutPath);
+  const match = /\/observability\/(\d{4}-\d{2}-\d{2})\//.exec(`/${normalized}`);
+  if (match) {
+    return match[1];
+  }
+  return normalizeIsoTimestamp(fallbackIso).slice(0, 10);
+}
+
+function normalizeSharedResources(raw = {}, { nowIso = new Date().toISOString() } = {}) {
+  const source = raw && typeof raw === "object" ? raw : {};
+  return {
+    provisionedIdentityIds: normalizeStringList(source.provisionedIdentityIds),
+    provisioningTags: normalizeStringList(source.provisioningTags),
+    provisionCount: normalizeNonNegativeInteger(source.provisionCount, 0),
+    lastProvisionedAt: source.lastProvisionedAt
+      ? normalizeIsoTimestamp(source.lastProvisionedAt, nowIso)
+      : null,
+    updatedAt: normalizeIsoTimestamp(source.updatedAt, nowIso),
+  };
+}
+
+function normalizeTemplateAgent(raw = {}) {
+  const source = raw && typeof raw === "object" ? raw : {};
+  return {
+    role: normalizeString(source.role) || "agent",
+    instructions: normalizeString(source.instructions) || "Follow session guidance.",
+  };
+}
+
+function normalizeSessionTemplate(raw = null) {
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const source = raw;
+  const id = normalizeString(source.id || source.name);
+  if (!id) {
+    return null;
+  }
+  const suggestedAgents = Array.isArray(source.suggestedAgents)
+    ? source.suggestedAgents.map((agent) => normalizeTemplateAgent(agent))
+    : [];
+  const ttlHours = normalizePositiveInteger(source.ttlHours, 1);
+  const normalizedAutoProvision =
+    source.autoProvisionEmails === undefined || source.autoProvisionEmails === null
+      ? null
+      : normalizePositiveInteger(source.autoProvisionEmails, 1);
+
+  return {
+    id,
+    version: normalizeString(source.version) || "1.0.0",
+    registryVersion: normalizeString(source.registryVersion) || "1.0.0",
+    description: normalizeString(source.description),
+    daemonModel: normalizeString(source.daemonModel),
+    ttlHours,
+    autoProvisionEmails: normalizedAutoProvision,
+    suggestedAgents,
+  };
+}
+
 async function collectSessionCodebaseContext(targetPath) {
   const cachedIngestPath = path.join(targetPath, ".sentinelayer", "CODEBASE_INGEST.json");
   const cachedIngest = await readJsonFile(cachedIngestPath, { allowMissing: true });
@@ -119,6 +216,102 @@ async function collectSessionCodebaseContext(targetPath) {
   return normalizeCodebaseContext(ingest);
 }
 
+async function buildArchiveSidecars(
+  sessionId,
+  {
+    targetPath,
+    outputDir = "",
+    env,
+    homeDir,
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedTargetPath = path.resolve(String(targetPath || "."));
+  const normalizedNow = normalizeIsoTimestamp(nowIso, new Date().toISOString());
+
+  const analytics = await computeSessionAnalytics(normalizedSessionId, {
+    targetPath: normalizedTargetPath,
+    outputDir,
+    env,
+    homeDir,
+    nowIso: normalizedNow,
+  });
+  const lineage = await buildArtifactLineageIndex({
+    targetPath: normalizedTargetPath,
+    outputDir,
+    env,
+    homeDir,
+    nowIso: normalizedNow,
+  });
+
+  const sessionWorkItems = Array.isArray(lineage.workItems)
+    ? lineage.workItems.filter(
+        (item) => normalizeString(item?.links?.sessionId) === normalizedSessionId
+      )
+    : [];
+  const verification = [];
+
+  for (const workItem of sessionWorkItems) {
+    const workItemId = normalizeString(workItem.workItemId);
+    if (!workItemId) {
+      continue;
+    }
+    const closeoutPath = normalizeString(workItem?.artifacts?.closeoutPath);
+    const dateKey = normalizeDateKeyFromCloseoutPath(closeoutPath, normalizedNow);
+    const chain = await verifyArtifactChain({
+      workItemId,
+      date: dateKey,
+      targetPath: normalizedTargetPath,
+      outputDir,
+      env,
+      homeDir,
+    });
+    verification.push({
+      workItemId,
+      date: chain.date,
+      closeoutPath: closeoutPath || null,
+      closeoutAnchorSha256: normalizeString(workItem?.artifacts?.closeoutAnchorSha256) || null,
+      valid: chain.valid,
+      mismatchCount: Array.isArray(chain.mismatches) ? chain.mismatches.length : 0,
+      mismatches: Array.isArray(chain.mismatches) ? chain.mismatches : [],
+    });
+    if (!chain.valid) {
+      throw new Error(
+        `Artifact chain verification failed for work item '${workItemId}' (${dateKey}).`
+      );
+    }
+  }
+
+  const analyticsSidecar = {
+    schemaVersion: "1.0.0",
+    generatedAt: normalizedNow,
+    sessionId: normalizedSessionId,
+    metrics: analytics,
+  };
+  const artifactChainSidecar = {
+    schemaVersion: "1.0.0",
+    generatedAt: normalizedNow,
+    sessionId: normalizedSessionId,
+    lineageRunId: normalizeString(lineage.lineageRunId) || null,
+    lineageIndexPath: toRelativePosix(
+      normalizedTargetPath,
+      normalizeString(lineage.indexPath)
+    ) || null,
+    summary: {
+      totalWorkItemsIndexed: Number(lineage?.summary?.totalWorkItemsIndexed || 0),
+      sessionWorkItems: sessionWorkItems.length,
+      verifiedWorkItems: verification.filter((item) => item.valid).length,
+    },
+    workItems: verification,
+  };
+
+  return {
+    analyticsSidecar,
+    artifactChainSidecar,
+  };
+}
+
 function normalizeSessionStatus(value) {
   const normalized = normalizeString(value).toLowerCase();
   if (normalized === SESSION_STATUS_EXPIRED) return SESSION_STATUS_EXPIRED;
@@ -147,6 +340,8 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
     s3Path: normalizeString(raw.s3Path) || null,
     archiveStatus: normalizeString(raw.archiveStatus) || "pending",
     codebaseContext: normalizeCodebaseContext(raw.codebaseContext || {}),
+    sharedResources: normalizeSharedResources(raw.sharedResources || {}, { nowIso }),
+    template: normalizeSessionTemplate(raw.template || null),
   };
 }
 
@@ -176,6 +371,8 @@ function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString())
     archivedAt: metadata.archivedAt,
     s3Path: metadata.s3Path,
     codebaseContext: metadata.codebaseContext,
+    sharedResources: metadata.sharedResources,
+    template: metadata.template,
   };
 }
 
@@ -208,6 +405,7 @@ async function saveMetadata(metadata, paths) {
 export async function createSession({
   targetPath = process.cwd(),
   ttlSeconds = DEFAULT_TTL_SECONDS,
+  template = null,
 } = {}) {
   const resolvedTargetPath = path.resolve(String(targetPath || "."));
   const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
@@ -234,6 +432,8 @@ export async function createSession({
       s3Path: null,
       archiveStatus: "pending",
       codebaseContext,
+      sharedResources: normalizeSharedResources({}, { nowIso }),
+      template: normalizeSessionTemplate(template),
     },
     {
       sessionId,
@@ -349,7 +549,14 @@ export async function expireSession(sessionId, { targetPath = process.cwd() } =
 
 export async function archiveSession(
   sessionId,
-  { s3Bucket, s3Prefix = "", targetPath = process.cwd() } = {}
+  {
+    s3Bucket,
+    s3Prefix = "",
+    targetPath = process.cwd(),
+    outputDir = "",
+    env,
+    homeDir,
+  } = {}
 ) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {
@@ -363,6 +570,13 @@ export async function archiveSession(
   const prefixSegment = normalizedPrefix ? `${normalizedPrefix}/` : "";
   const s3Path = `s3://${normalizedBucket}/${prefixSegment}sessions/${loaded.paths.sessionId}/`;
   const nowIso = new Date().toISOString();
+  const sidecars = await buildArchiveSidecars(loaded.paths.sessionId, {
+    targetPath: loaded.targetPath,
+    outputDir,
+    env,
+    homeDir,
+    nowIso,
+  });
 
   loaded.metadata.status = SESSION_STATUS_ARCHIVED;
   loaded.metadata.archivedAt = nowIso;
@@ -371,13 +585,115 @@ export async function archiveSession(
   loaded.metadata.s3Path = s3Path;
   const saved = await saveMetadata(loaded.metadata, loaded.paths);
 
+  await Promise.all([
+    writeJsonFile(path.join(loaded.paths.sessionDir, "analytics.json"), sidecars.analyticsSidecar),
+    writeJsonFile(
+      path.join(loaded.paths.sessionDir, "artifact-chain.json"),
+      sidecars.artifactChainSidecar
+    ),
+  ]);
   await writeJsonFile(path.join(loaded.paths.sessionDir, "archive-manifest.json"), {
     sessionId: loaded.paths.sessionId,
     archivedAt: nowIso,
     s3Path,
-    files: ["metadata.json", "stream.ndjson", "stream.1.ndjson", "agents/"],
+    files: [
+      "metadata.json",
+      "stream.ndjson",
+      "stream.1.ndjson",
+      "agents/",
+      "analytics.json",
+      "artifact-chain.json",
+    ],
+  });
+
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
+// Emit analytics.json + artifact-chain.json for a live session without archiving.
+// Callers should invoke this on a timer (spec §PR 10 line 1451: "S3 archive
+// carries analytics.json sidecar" + line 1452-1453: closeout.json observability
+// invariant — mid-flight observability requires the sidecar on disk too).
+// Safe to call frequently; the payload is idempotent per (sessionId, nowIso).
+export async function persistSessionSidecarsSnapshot(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    outputDir = "",
+    env = process.env,
+    homeDir,
+    nowIso = new Date().toISOString(),
+  } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    throw new Error(`Session '${sessionId}' was not found.`);
+  }
+  const sidecars = await buildArchiveSidecars(loaded.paths.sessionId, {
+    targetPath: loaded.targetPath,
+    outputDir,
+    env,
+    homeDir,
+    nowIso,
+  });
+  await Promise.all([
+    writeJsonFile(path.join(loaded.paths.sessionDir, "analytics.json"), sidecars.analyticsSidecar),
+    writeJsonFile(
+      path.join(loaded.paths.sessionDir, "artifact-chain.json"),
+      sidecars.artifactChainSidecar
+    ),
+  ]);
+  return {
+    sessionId: loaded.paths.sessionId,
+    analyticsSidecar: sidecars.analyticsSidecar,
+    artifactChainSidecar: sidecars.artifactChainSidecar,
+  };
+}
+
+export async function recordSessionProvisionedIdentities(
+  sessionId,
+  { targetPath = process.cwd(), identityIds = [], tags = [] } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    throw new Error(`Session '${sessionId}' was not found.`);
+  }
+
+  const nowIso = new Date().toISOString();
+  const normalizedIdentityIds = normalizeStringList(identityIds);
+  if (normalizedIdentityIds.length === 0) {
+    return buildSessionPayload(loaded.metadata, loaded.paths, nowIso);
+  }
+
+  const existingSharedResources = normalizeSharedResources(loaded.metadata.sharedResources || {}, {
+    nowIso,
   });
+  const mergedIdentityIds = normalizeStringList([
+    ...existingSharedResources.provisionedIdentityIds,
+    ...normalizedIdentityIds,
+  ]);
+  const mergedTags = normalizeStringList([
+    ...existingSharedResources.provisioningTags,
+    ...normalizeStringList(tags),
+  ]);
+
+  loaded.metadata.sharedResources = normalizeSharedResources(
+    {
+      ...existingSharedResources,
+      provisionedIdentityIds: mergedIdentityIds,
+      provisioningTags: mergedTags,
+      provisionCount:
+        normalizeNonNegativeInteger(existingSharedResources.provisionCount, 0) +
+        normalizedIdentityIds.length,
+      lastProvisionedAt: nowIso,
+      updatedAt: nowIso,
+    },
+    { nowIso }
+  );
+  loaded.metadata.updatedAt = nowIso;
+  loaded.metadata.lastInteractionAt = nowIso;
+  loaded.metadata.status = SESSION_STATUS_ACTIVE;
 
+  const saved = await saveMetadata(loaded.metadata, loaded.paths);
   return buildSessionPayload(saved, loaded.paths, nowIso);
 }
 

package/src/session/stream.js

@@ -4,6 +4,8 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { createAgentEvent, normalizeAgentEvent } from "../events/schema.js";
 import { resolveSessionPaths } from "./paths.js";
+import { redactEventPayload } from "./redact.js";
+import { syncSessionEventToApi } from "./sync.js";
 
 const DEFAULT_POLL_MS = 500;
 const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
@@ -232,7 +234,8 @@ export async function appendToStream(
     throw new Error(`Session '${paths.sessionId}' is expired and does not accept new events.`);
   }
 
-  const canonicalEvent = materializeCanonicalEvent(paths.sessionId, event);
+  const rawEvent = materializeCanonicalEvent(paths.sessionId, event);
+  const canonicalEvent = redactEventPayload(rawEvent);
   const nowIso = new Date().toISOString();
   const normalizedMaxEvents = normalizePositiveInteger(maxEvents, DEFAULT_MAX_STREAM_EVENTS);
 
@@ -249,6 +252,11 @@ export async function appendToStream(
     await releaseLock(paths.lockPath);
   }
 
+  // Best-effort dashboard sync. Never block local stream durability on API state.
+  void syncSessionEventToApi(paths.sessionId, canonicalEvent, {
+    targetPath,
+  }).catch(() => {});
+
   return canonicalEvent;
 }