sentinelayer-cli 0.8.11 → 0.9.0

package/src/commands/session.js

@@ -47,6 +47,7 @@ import {
   listActiveSessions,
   listAllSessions,
   recordSessionProvisionedIdentities,
+  updateSessionTitle,
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import { readSessionPreview } from "../session/preview.js";
@@ -57,6 +58,8 @@ import {
 } from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
+import { listenSessionEvents } from "../session/listener.js";
+import { deriveSessionTitle } from "../session/senti-naming.js";
 import {
   buildDashboardUrl,
   buildTemplateLaunchPlan,
@@ -88,6 +91,233 @@ function parsePositiveInteger(rawValue, field, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function normalizeComparablePath(value) {
+  return String(value || "")
+    .trim()
+    .replace(/\\/g, "/")
+    .replace(/\/+$/g, "")
+    .toLowerCase();
+}
+
+function latestSessionActivityMs(entry = {}) {
+  for (const key of ["lastInteractionAt", "lastActivityAt", "createdAt"]) {
+    const epoch = Date.parse(normalizeString(entry[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+function remoteSessionLookupDisabled() {
+  return String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1";
+}
+
+function mergeResumeCandidate(existing, incoming) {
+  if (!existing) return incoming;
+  const existingActivity = Number(existing._activityMs || 0);
+  const incomingActivity = Number(incoming._activityMs || 0);
+  const preferIncomingPaths = existing._source !== "local" && incoming._source === "local";
+  const base = preferIncomingPaths ? incoming : existing;
+  const other = preferIncomingPaths ? existing : incoming;
+  return {
+    ...base,
+    title: normalizeString(base.title) || normalizeString(other.title) || null,
+    lastActivityAt:
+      normalizeString(incoming.lastActivityAt) || normalizeString(existing.lastActivityAt) || null,
+    lastInteractionAt:
+      normalizeString(incoming.lastInteractionAt) || normalizeString(existing.lastInteractionAt) || null,
+    _activityMs: Math.max(existingActivity, incomingActivity),
+  };
+}
+
+async function findReusableSessionCandidate({
+  targetPath,
+  reuseWindowSeconds = 3600,
+  resume = true,
+  forceNew = false,
+} = {}) {
+  if (forceNew || resume === false) return null;
+  const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
+  const byId = new Map();
+
+  try {
+    const active = await listActiveSessions({ targetPath });
+    for (const entry of active) {
+      const activityMs = latestSessionActivityMs(entry);
+      if (!activityMs || activityMs < cutoffMs) continue;
+      const candidate = {
+        ...entry,
+        _source: "local",
+        _activityMs: activityMs,
+      };
+      byId.set(entry.sessionId, mergeResumeCandidate(byId.get(entry.sessionId), candidate));
+    }
+  } catch {
+    /* local lookup failure is non-fatal */
+  }
+
+  if (!remoteSessionLookupDisabled()) {
+    try {
+      const remote = await listSessionsFromApi({
+        targetPath,
+        includeArchived: false,
+        limit: 50,
+      });
+      if (remote && remote.ok) {
+        const normalizedTarget = normalizeComparablePath(targetPath);
+        for (const entry of remote.sessions || []) {
+          const codebase = normalizeComparablePath(entry.codebasePath || entry.targetPath);
+          if (!codebase || codebase !== normalizedTarget) continue;
+          if (entry.archiveStatus && entry.archiveStatus !== "active") continue;
+          const activityMs = latestSessionActivityMs(entry);
+          if (!activityMs || activityMs < cutoffMs) continue;
+          const candidate = {
+            sessionId: entry.sessionId,
+            createdAt: entry.createdAt,
+            lastActivityAt: entry.lastActivityAt,
+            expiresAt: entry.expiresAt,
+            status: entry.status || "active",
+            template: entry.templateName || null,
+            title: entry.title || null,
+            _source: "remote",
+            _activityMs: activityMs,
+          };
+          byId.set(entry.sessionId, mergeResumeCandidate(byId.get(entry.sessionId), candidate));
+        }
+      }
+    } catch {
+      /* remote lookup failure is non-fatal */
+    }
+  }
+
+  const candidates = [...byId.values()];
+  candidates.sort((left, right) => Number(right._activityMs || 0) - Number(left._activityMs || 0));
+  return candidates[0] || null;
+}
+
+async function pushSessionTitleToApi(sessionId, title, { targetPath } = {}) {
+  const normalizedTitle = normalizeString(title);
+  if (!normalizedTitle || remoteSessionLookupDisabled()) return;
+  try {
+    const session = await resolveActiveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+    if (!session?.token || !session?.apiUrl) return;
+    const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
+    await requestJsonMutation(
+      `${apiUrl}/api/v1/sessions/${encodeURIComponent(sessionId)}/title`,
+      {
+        method: "POST",
+        operationName: "session.set_title",
+        headers: { Authorization: `Bearer ${session.token}` },
+        body: { title: normalizedTitle },
+      },
+    );
+  } catch {
+    /* best-effort */
+  }
+}
+
+async function ensureWorkspaceSession({
+  targetPath,
+  ttlSeconds = DEFAULT_TTL_SECONDS,
+  template = null,
+  title = "",
+  resume = true,
+  forceNew = false,
+  reuseWindowSeconds = 3600,
+} = {}) {
+  const titleArg = normalizeString(title);
+  const fallbackTitle = deriveSessionTitle(targetPath);
+  const startedAt = Date.now();
+  const resumedCandidate = await findReusableSessionCandidate({
+    targetPath,
+    reuseWindowSeconds,
+    resume,
+    forceNew,
+  });
+  let created;
+  const resumeTitle =
+    titleArg || normalizeString(resumedCandidate?.title) || fallbackTitle;
+
+  if (resumedCandidate) {
+    if (resumedCandidate._source === "remote" && !resumedCandidate.sessionDir) {
+      created = await createSession({
+        targetPath,
+        ttlSeconds,
+        sessionId: resumedCandidate.sessionId,
+        title: resumeTitle,
+        createdAt: resumedCandidate.createdAt,
+        expiresAt: resumedCandidate.expiresAt,
+        lastInteractionAt:
+          resumedCandidate.lastInteractionAt ||
+          resumedCandidate.lastActivityAt ||
+          resumedCandidate.createdAt,
+      });
+    } else {
+      created = {
+        sessionId: resumedCandidate.sessionId,
+        sessionDir: resumedCandidate.sessionDir || null,
+        metadataPath: resumedCandidate.metadataPath || null,
+        streamPath: resumedCandidate.streamPath || null,
+        createdAt: resumedCandidate.createdAt,
+        updatedAt: resumedCandidate.updatedAt || null,
+        lastInteractionAt: resumedCandidate.lastInteractionAt || null,
+        expiresAt: resumedCandidate.expiresAt,
+        elapsedTimer: resumedCandidate.elapsedTimer || 0,
+        renewalCount: resumedCandidate.renewalCount || 0,
+        status: resumedCandidate.status || "active",
+        template: resumedCandidate.template || null,
+        title: normalizeString(resumedCandidate.title) || null,
+        codebaseContext: resumedCandidate.codebaseContext || null,
+      };
+      if (resumeTitle && resumeTitle !== created.title) {
+        const updated = await updateSessionTitle(created.sessionId, {
+          targetPath,
+          title: resumeTitle,
+        }).catch(() => null);
+        if (updated) {
+          created = {
+            ...created,
+            ...updated,
+          };
+        }
+      }
+    }
+  } else {
+    created = await createSession({
+      targetPath,
+      ttlSeconds,
+      template,
+      title: titleArg || fallbackTitle,
+    });
+  }
+
+  const effectiveTitle = titleArg || normalizeString(created.title) || fallbackTitle;
+  const titleAuto = !titleArg && !resumedCandidate;
+  const shouldPushTitle = Boolean(
+    titleArg ||
+      titleAuto ||
+      (resumedCandidate && effectiveTitle && !normalizeString(resumedCandidate.title))
+  );
+  if (shouldPushTitle) {
+    void pushSessionTitleToApi(created.sessionId, effectiveTitle, { targetPath });
+  }
+
+  return {
+    created: {
+      ...created,
+      title: effectiveTitle || null,
+      resumed: Boolean(resumedCandidate),
+    },
+    resumedCandidate,
+    durationMs: Date.now() - startedAt,
+    title: effectiveTitle || null,
+    titleAuto,
+  };
+}
+
 function normalizeAgentId(value, fallbackValue = "cli-user") {
   const normalized = normalizeString(value)
     .toLowerCase()
@@ -278,6 +508,15 @@ export function registerSessionCommand(program) {
       "--force-new",
       "Always create a new session even if a recent active one exists for this workspace",
     )
+    .option(
+      "--resume",
+      "Reuse the most recent active session for this workspace when one is inside the reuse window",
+      true,
+    )
+    .option(
+      "--no-resume",
+      "Disable automatic resume and mint a new session unless --force-new is also present",
+    )
     .option(
       "--reuse-window-seconds <seconds>",
       "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
@@ -301,91 +540,22 @@ export function registerSessionCommand(program) {
         "reuse-window-seconds",
         3600,
       );
-
-      // Auto-resume: if there's an active local session for this same
-      // workspace path created in the last `reuseWindowSeconds`, reuse
-      // it instead of minting a new id. Kills the orphan-creation
-      // pattern where every CLI invocation produced a fresh empty
-      // session. `--force-new` opts back into the old behavior.
-      let resumed = null;
-      if (!options.forceNew) {
-        try {
-          const active = await listActiveSessions({ targetPath });
-          const cutoffMs = Date.now() - reuseWindowSeconds * 1000;
-          const candidates = active.filter((entry) => {
-            const createdMs = Date.parse(entry.createdAt || "");
-            return Number.isFinite(createdMs) && createdMs >= cutoffMs;
-          });
-          candidates.sort((a, b) =>
-            String(b.lastActivityAt || b.createdAt || "").localeCompare(
-              String(a.lastActivityAt || a.createdAt || ""),
-            ),
-          );
-          if (candidates.length > 0) {
-            resumed = candidates[0];
-          }
-        } catch (error) {
-          // listActiveSessions failure is non-fatal; fall through to fresh create.
-        }
-      }
-
-      const startedAt = Date.now();
-      let created;
-      if (resumed) {
-        // Surface the resumed session's metadata in the same shape
-        // createSession returns so downstream code stays unchanged.
-        created = {
-          sessionId: resumed.sessionId,
-          sessionDir: resumed.sessionDir || null,
-          metadataPath: resumed.metadataPath || null,
-          streamPath: resumed.streamPath || null,
-          createdAt: resumed.createdAt,
-          expiresAt: resumed.expiresAt,
-          elapsedTimer: 0,
-          renewalCount: resumed.renewalCount || 0,
-          status: resumed.status || "active",
-          template: resumed.template || null,
-          codebaseContext: resumed.codebaseContext || null,
-          resumed: true,
-        };
-      } else {
-        created = await createSession({
-          targetPath,
-          ttlSeconds,
-          template,
-        });
-      }
-      const durationMs = Date.now() - startedAt;
+      const titleArg = normalizeString(options.title);
+      const ensured = await ensureWorkspaceSession({
+        targetPath,
+        ttlSeconds,
+        template,
+        title: titleArg,
+        resume: options.resume !== false,
+        forceNew: Boolean(options.forceNew),
+        reuseWindowSeconds,
+      });
+      const created = ensured.created;
+      const resumed = Boolean(ensured.resumedCandidate);
+      const durationMs = ensured.durationMs;
       const launchPlan = template ? buildTemplateLaunchPlan(created.sessionId, template) : [];
       const dashboardUrl = buildDashboardUrl(created.sessionId);
-      const titleArg = normalizeString(options.title);
-
-      // If the caller passed --title, push it to the API so the web
-      // sidebar shows the label (best-effort, non-blocking).
-      if (titleArg) {
-        void (async () => {
-          try {
-            const session = await resolveActiveAuthSession({
-              cwd: targetPath,
-              env: process.env,
-              autoRotate: false,
-            });
-            if (!session?.token || !session?.apiUrl) return;
-            const apiUrl = String(session.apiUrl).replace(/\/+$/, "");
-            await requestJsonMutation(
-              `${apiUrl}/api/v1/sessions/${encodeURIComponent(created.sessionId)}/title`,
-              {
-                method: "POST",
-                operationName: "session.set_title",
-                headers: { Authorization: `Bearer ${session.token}` },
-                body: { title: titleArg },
-              },
-            );
-          } catch (_error) {
-            /* best-effort */
-          }
-        })();
-      }
+      const effectiveTitle = ensured.title;
 
       const payload = {
         command: "session start",
@@ -396,7 +566,9 @@ export function registerSessionCommand(program) {
         metadataPath: created.metadataPath,
         streamPath: created.streamPath,
         createdAt: created.createdAt,
+        updatedAt: created.updatedAt,
         expiresAt: created.expiresAt,
+        lastInteractionAt: created.lastInteractionAt,
         ttlSeconds,
         elapsedTimer: created.elapsedTimer,
         renewalCount: created.renewalCount,
@@ -404,8 +576,9 @@ export function registerSessionCommand(program) {
         template: created.template,
         launchPlan,
         dashboardUrl,
-        resumed: Boolean(resumed),
-        title: titleArg || null,
+        resumed,
+        title: effectiveTitle || null,
+        titleAuto: Boolean(ensured.titleAuto),
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
@@ -415,6 +588,7 @@ export function registerSessionCommand(program) {
         status: created.status,
         createdAt: created.createdAt,
         expiresAt: created.expiresAt,
+        title: effectiveTitle || null,
         ttlSeconds,
         template: created.template,
         codebaseContext: created.codebaseContext,
@@ -475,6 +649,62 @@ export function registerSessionCommand(program) {
       await program.parseAsync(args, { from: "user" });
     });
 
+  session
+    .command("ensure")
+    .description("Join or create the canonical session for this workspace and emit JSON")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--title <title>", "Title applied if a new or unnamed resumed session needs one")
+    .option(
+      "--ttl-seconds <seconds>",
+      `Session time-to-live in seconds when a new session is minted (default ${DEFAULT_TTL_SECONDS})`
+    )
+    .option(
+      "--force-new",
+      "Always create a new session even if a recent active one exists for this workspace",
+    )
+    .option(
+      "--resume",
+      "Reuse the most recent active session for this workspace when one is inside the reuse window",
+      true,
+    )
+    .option("--no-resume", "Disable automatic resume and mint a new session")
+    .option(
+      "--reuse-window-seconds <seconds>",
+      "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
+      "3600",
+    )
+    .option("--json", "Emit machine-readable output (default for this command)")
+    .action(async (options) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const ttlSeconds = parsePositiveInteger(
+        options.ttlSeconds,
+        "ttl-seconds",
+        DEFAULT_TTL_SECONDS,
+      );
+      const reuseWindowSeconds = parsePositiveInteger(
+        options.reuseWindowSeconds,
+        "reuse-window-seconds",
+        3600,
+      );
+      const ensured = await ensureWorkspaceSession({
+        targetPath,
+        ttlSeconds,
+        title: normalizeString(options.title),
+        resume: options.resume !== false,
+        forceNew: Boolean(options.forceNew),
+        reuseWindowSeconds,
+      });
+      const payload = {
+        command: "session ensure",
+        targetPath,
+        sessionId: ensured.created.sessionId,
+        title: ensured.title || null,
+        resumed: Boolean(ensured.resumedCandidate),
+        dashboardUrl: buildDashboardUrl(ensured.created.sessionId),
+      };
+      console.log(JSON.stringify(payload, null, 2));
+    });
+
   session
     .command("set-title <sessionId> <title>")
     .description("Set the human-readable title on a session (visible in web sidebar + transcript).")
@@ -504,10 +734,15 @@ export function registerSessionCommand(program) {
           body: { title: normalizedTitle },
         },
       );
+      const localUpdated = await updateSessionTitle(normalizedSessionId, {
+        targetPath,
+        title: normalizedTitle,
+      }).catch(() => null);
       const payload = {
         command: "session set-title",
         sessionId: normalizedSessionId,
         title: normalizedTitle,
+        localUpdated: Boolean(localUpdated),
         result,
       };
       if (shouldEmitJson(options, command)) {
@@ -637,6 +872,7 @@ export function registerSessionCommand(program) {
     .command("say <sessionId> <message>")
     .description("Send a message to the session")
     .option("--agent <id>", "Agent id to emit from", "cli-user")
+    .option("--to <agent>", "Direct the message to a specific agent id")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--json", "Emit machine-readable output")
     .action(async (sessionId, message, options, command) => {
@@ -650,14 +886,19 @@ export function registerSessionCommand(program) {
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const agentId = normalizeAgentId(options.agent, "cli-user");
+      const to = normalizeString(options.to);
+      const eventPayload = {
+        message: normalizedMessage,
+        channel: "session",
+      };
+      if (to) {
+        eventPayload.to = to;
+      }
       const event = createAgentEvent({
         event: "session_message",
         agentId,
         sessionId: normalizedSessionId,
-        payload: {
-          message: normalizedMessage,
-          channel: "session",
-        },
+        payload: eventPayload,
       });
       const persisted = await appendToStream(normalizedSessionId, event, {
         targetPath,
@@ -676,6 +917,93 @@ export function registerSessionCommand(program) {
       console.log(formatEventLine(persisted));
     });
 
+  session
+    .command("listen")
+    .description("Background-poll a session for events addressed to this agent or broadcast")
+    .requiredOption("--session <id>", "Session id to listen to")
+    .option(
+      "--agent <id>",
+      "Agent id to receive messages for",
+      process.env.SENTINELAYER_AGENT_ID || "cli-user",
+    )
+    .option("--interval <seconds>", "Polling interval in seconds (default 60)", "60")
+    .option("--emit <format>", "Output format: ndjson or text", "ndjson")
+    .option("--limit <n>", "Maximum events to request per poll (default 200)", "200")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--since <cursor>", "Override the persisted listen cursor")
+    .option("--replay", "Emit matching historical events on the first poll")
+    .option("--max-polls <n>", "Stop after N poll cycles (useful for tests and smoke checks)")
+    .action(async (options) => {
+      const normalizedSessionId = resolveSessionIdOption(options);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "cli-user");
+      const intervalSeconds = parsePositiveInteger(options.interval, "interval", 60);
+      const limit = parsePositiveInteger(options.limit, "limit", 200);
+      const emitFormat = normalizeString(options.emit).toLowerCase() || "ndjson";
+      if (!["ndjson", "text"].includes(emitFormat)) {
+        throw new Error("--emit must be one of: ndjson, text.");
+      }
+      const maxPolls =
+        options.maxPolls === undefined
+          ? null
+          : parsePositiveInteger(options.maxPolls, "max-polls", 1);
+      const since = options.since === undefined ? undefined : String(options.since);
+      const ac = new AbortController();
+      const onSigint = () => ac.abort();
+      process.on("SIGINT", onSigint);
+
+      if (emitFormat === "text") {
+        console.log(
+          pc.gray(
+            `Listening to session ${normalizedSessionId} as ${agentId}; interval=${intervalSeconds}s. Press Ctrl+C to stop.`,
+          ),
+        );
+      }
+
+      try {
+        await listenSessionEvents({
+          sessionId: normalizedSessionId,
+          targetPath,
+          agentId,
+          intervalSeconds,
+          limit,
+          since,
+          replay: Boolean(options.replay),
+          maxPolls,
+          signal: ac.signal,
+          onEvent: async (event) => {
+            if (emitFormat === "ndjson") {
+              console.log(JSON.stringify(event));
+            } else {
+              console.log(formatEventLine(event));
+            }
+          },
+          onError: async (result) => {
+            const reason = normalizeString(result?.reason) || "poll_failed";
+            if (emitFormat === "ndjson") {
+              console.log(
+                JSON.stringify(
+                  createAgentEvent({
+                    event: "session_listen_error",
+                    agentId,
+                    sessionId: normalizedSessionId,
+                    payload: {
+                      reason,
+                      cursor: result?.cursor || null,
+                    },
+                  }),
+                ),
+              );
+            } else {
+              console.log(pc.yellow(`Listen poll skipped (${reason}).`));
+            }
+          },
+        });
+      } finally {
+        process.removeListener("SIGINT", onSigint);
+      }
+    });
+
   session
     .command("read <sessionId>")
     .description("Read recent session messages")

package/src/commands/swarm.js

@@ -517,6 +517,9 @@ export function registerSwarmCommand(program) {
     .option("--scenario-file <path>", "Scenario DSL file (.sls) for runtime actions")
     .option("--registry-file <path>", "Optional custom swarm registry file (when building plan inline)")
     .option("--agents <ids>", "Comma-separated agent ids for inline plan mode", "security,testing,reliability")
+    .option("--agent <id>", "Single agent id alias for --agents")
+    .option("--scope <scope>", "Runtime scope alias for --scenario, used by devTestBot")
+    .option("--identity-id <id>", "AIdenID identity id for devTestBot runtime")
     .option("--scenario <id>", "Scenario identifier for inline plan mode", "qa_audit")
     .option(
       "--objective <text>",
@@ -571,7 +574,7 @@ export function registerSwarmCommand(program) {
         const registry = await loadSwarmRegistry({
           registryFile: options.registryFile,
         });
-        const selected = selectSwarmAgents(registry.agents, options.agents);
+        const selected = selectSwarmAgents(registry.agents, options.agent || options.agents);
         if (selected.missing.length > 0) {
           throw new Error(`Unknown agent id(s): ${selected.missing.join(", ")}`);
         }
@@ -581,7 +584,7 @@ export function registerSwarmCommand(program) {
         const selectedAgents = ensureOmarIncluded(registry.agents, selected.selected);
         plan = buildSwarmExecutionPlan({
           targetPath,
-          scenario: scenarioIdOverride || options.scenario,
+          scenario: scenarioIdOverride || options.scope || options.scenario,
           objective: options.objective,
           agents: selectedAgents,
           maxParallel: parseMaxParallel(options.maxParallel),
@@ -612,6 +615,8 @@ export function registerSwarmCommand(program) {
         execute: Boolean(options.execute),
         maxSteps: parseMaxSteps(options.maxSteps),
         startUrl: startUrlOverride || options.startUrl,
+        identityId: options.identityId,
+        devTestBotScope: options.scope || scenarioIdOverride || options.scenario,
         playbookActions,
         outputDir: options.outputDir,
         env: process.env,
@@ -631,6 +636,10 @@ export function registerSwarmCommand(program) {
         stop: runtime.stop,
         usage: runtime.usage,
         eventCount: runtime.eventCount,
+        findingCount: runtime.findingCount,
+        findings: runtime.findings,
+        artifactBundles: runtime.artifactBundles,
+        devTestBotRuns: runtime.devTestBotRuns,
         runtimeDirectory: runtime.runtimeDirectory,
         runtimeJsonPath: runtime.runtimeJsonPath,
         runtimeMarkdownPath: runtime.runtimeMarkdownPath,