sentinelayer-cli 0.4.5 → 0.8.0

package/src/commands/session.js

@@ -0,0 +1,590 @@
+import path from "node:path";
+import process from "node:process";
+
+import pc from "picocolors";
+
+import {
+  listAssignments,
+  releaseLease,
+} from "../daemon/assignment-ledger.js";
+import { stopScopeEngine } from "../daemon/scope-engine.js";
+import { createAgentEvent } from "../events/schema.js";
+import {
+  detectStaleAgents,
+  listAgents,
+  registerAgent,
+  unregisterAgent,
+} from "../session/agent-registry.js";
+import { stopSenti } from "../session/daemon.js";
+import { listRuntimeRuns } from "../session/runtime-bridge.js";
+import {
+  createSession,
+  DEFAULT_TTL_SECONDS,
+  getSession,
+  listActiveSessions,
+} from "../session/store.js";
+import { appendToStream, readStream, tailStream } from "../session/stream.js";
+
+function shouldEmitJson(options, command) {
+  const local = Boolean(options && options.json);
+  const globalFromCommand =
+    command && command.optsWithGlobals ? Boolean(command.optsWithGlobals().json) : false;
+  return local || globalFromCommand;
+}
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function parsePositiveInteger(rawValue, field, fallbackValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(rawValue);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+  return Math.floor(normalized);
+}
+
+function normalizeAgentId(value, fallbackValue = "cli-user") {
+  const normalized = normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || fallbackValue;
+}
+
+function resolveSessionIdOption(options = {}) {
+  const sessionId = normalizeString(options.session || options.id);
+  if (!sessionId) {
+    throw new Error("session id is required (use --session <id>).");
+  }
+  return sessionId;
+}
+
+function formatEventLine(event = {}) {
+  const ts = normalizeString(event.ts || event.timestamp);
+  const type = normalizeString(event.event || event.type) || "event";
+  const agentId = normalizeString(event.agent?.id || event.agentId || "unknown");
+  const payload = event.payload && typeof event.payload === "object" ? event.payload : {};
+  const message = normalizeString(payload.message || payload.response || payload.alert || payload.reason || "");
+  if (message) {
+    return `${ts} ${agentId} ${type}: ${message}`;
+  }
+  return `${ts} ${agentId} ${type}`;
+}
+
+async function revokeAgentLeases(sessionId, agentId, { targetPath, reason } = {}) {
+  const active = await listAssignments({
+    targetPath,
+    sessionId,
+    agentIdentity: agentId,
+    statuses: ["CLAIMED", "IN_PROGRESS"],
+    includeExpired: true,
+    limit: 500,
+  });
+  let releasedCount = 0;
+  for (const assignment of active.assignments) {
+    await releaseLease({
+      targetPath,
+      sessionId,
+      workItemId: assignment.workItemId,
+      agentIdentity: agentId,
+      status: "QUEUED",
+      reason,
+    });
+    releasedCount += 1;
+  }
+  return releasedCount;
+}
+
+async function emitAgentKilledEvent(sessionId, agentId, {
+  targetPath,
+  reason,
+  leaseRevocations = 0,
+} = {}) {
+  const event = createAgentEvent({
+    event: "agent_killed",
+    agentId,
+    sessionId,
+    payload: {
+      target: agentId,
+      reason: normalizeString(reason) || "manual_stop",
+      leaseRevocations: Number(leaseRevocations || 0),
+    },
+  });
+  await appendToStream(sessionId, event, { targetPath });
+  return event;
+}
+
+export function registerSessionCommand(program) {
+  const session = program
+    .command("session")
+    .description("Multi-agent ephemeral coordination sessions");
+
+  session
+    .command("start")
+    .description("Create a new persistent session with metadata + NDJSON stream")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option(
+      "--ttl-seconds <seconds>",
+      `Session time-to-live in seconds (default ${DEFAULT_TTL_SECONDS})`,
+      String(DEFAULT_TTL_SECONDS)
+    )
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const ttlSeconds = parsePositiveInteger(options.ttlSeconds, "ttl-seconds", DEFAULT_TTL_SECONDS);
+      const startedAt = Date.now();
+      const created = await createSession({
+        targetPath,
+        ttlSeconds,
+      });
+      const durationMs = Date.now() - startedAt;
+
+      const payload = {
+        command: "session start",
+        targetPath,
+        durationMs,
+        sessionId: created.sessionId,
+        sessionDir: created.sessionDir,
+        metadataPath: created.metadataPath,
+        streamPath: created.streamPath,
+        createdAt: created.createdAt,
+        expiresAt: created.expiresAt,
+        elapsedTimer: created.elapsedTimer,
+        renewalCount: created.renewalCount,
+        status: created.status,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.bold("Session created"));
+      console.log(pc.gray(`Session: ${created.sessionId}`));
+      console.log(pc.gray(`Stream: ${created.streamPath}`));
+      console.log(pc.gray(`Created in ${durationMs}ms`));
+      console.log(
+        `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`
+      );
+    });
+
+  session
+    .command("join <sessionId>")
+    .description("Join an active session")
+    .option("--name <name>", "Agent display name")
+    .option("--role <role>", "Agent role: coder, reviewer, tester, observer", "coder")
+    .option("--model <model>", "Agent model hint", "cli")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .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 joined = await registerAgent(normalizedSessionId, {
+        targetPath,
+        agentId: normalizeAgentId(options.name, "cli-user"),
+        model: normalizeString(options.model) || "cli",
+        role: options.role || "coder",
+      });
+      const payload = {
+        command: "session join",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId: joined.agentId,
+        role: joined.role,
+        model: joined.model,
+        status: joined.status,
+        joinedAt: joined.joinedAt,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Joined session ${normalizedSessionId}`));
+      console.log(pc.gray(`agent=${joined.agentId} role=${joined.role} model=${joined.model}`));
+    });
+
+  session
+    .command("say <sessionId> <message>")
+    .description("Send a message to the session")
+    .option("--agent <id>", "Agent id to emit from", "cli-user")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, message, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const normalizedMessage = normalizeString(message);
+      if (!normalizedMessage) {
+        throw new Error("message is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const agentId = normalizeAgentId(options.agent, "cli-user");
+      const event = createAgentEvent({
+        event: "session_message",
+        agentId,
+        sessionId: normalizedSessionId,
+        payload: {
+          message: normalizedMessage,
+          channel: "session",
+        },
+      });
+      const persisted = await appendToStream(normalizedSessionId, event, {
+        targetPath,
+      });
+      const payload = {
+        command: "session say",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId,
+        event: persisted,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(formatEventLine(persisted));
+    });
+
+  session
+    .command("read <sessionId>")
+    .description("Read recent session messages")
+    .option("--tail <n>", "Number of recent events", "20")
+    .option("--follow", "Continuously follow new events")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .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 tail = parsePositiveInteger(options.tail, "tail", 20);
+      const emitJson = shouldEmitJson(options, command);
+
+      if (!options.follow) {
+        const events = await readStream(normalizedSessionId, {
+          targetPath,
+          tail,
+        });
+        const payload = {
+          command: "session read",
+          targetPath,
+          sessionId: normalizedSessionId,
+          tail,
+          count: events.length,
+          events,
+        };
+        if (emitJson) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+        for (const event of events) {
+          console.log(formatEventLine(event));
+        }
+        return;
+      }
+
+      if (!emitJson) {
+        console.log(pc.gray(`Following session ${normalizedSessionId}... Press Ctrl+C to stop.`));
+      }
+      for await (const event of tailStream(normalizedSessionId, {
+        targetPath,
+        replayTail: tail,
+      })) {
+        if (emitJson) {
+          console.log(JSON.stringify(event));
+        } else {
+          console.log(formatEventLine(event));
+        }
+      }
+    });
+
+  session
+    .command("status <sessionId>")
+    .description("Show session status, agents, and health")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .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 sessionPayload = await getSession(normalizedSessionId, {
+        targetPath,
+      });
+      if (!sessionPayload) {
+        throw new Error(`Session '${normalizedSessionId}' was not found.`);
+      }
+
+      const [agents, runtimeRuns, leases, recentEvents] = await Promise.all([
+        listAgents(normalizedSessionId, {
+          targetPath,
+          includeInactive: false,
+        }),
+        Promise.resolve(
+          listRuntimeRuns({
+            sessionId: normalizedSessionId,
+            targetPath,
+            includeStopped: false,
+          })
+        ),
+        listAssignments({
+          targetPath,
+          sessionId: normalizedSessionId,
+          statuses: ["CLAIMED", "IN_PROGRESS"],
+          includeExpired: true,
+          limit: 100,
+        }),
+        readStream(normalizedSessionId, {
+          targetPath,
+          tail: 10,
+        }),
+      ]);
+
+      const staleAgents = detectStaleAgents(agents, {});
+      const payload = {
+        command: "session status",
+        targetPath,
+        sessionId: normalizedSessionId,
+        session: sessionPayload,
+        activeAgents: agents,
+        staleAgents,
+        runtimeRuns,
+        activeLeases: leases.assignments,
+        recentEvents,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.bold(`Session ${normalizedSessionId}`));
+      console.log(
+        pc.gray(
+          `status=${sessionPayload.status} agents=${agents.length} stale=${staleAgents.length} runs=${runtimeRuns.length} leases=${leases.assignments.length}`
+        )
+      );
+      for (const event of recentEvents) {
+        console.log(formatEventLine(event));
+      }
+    });
+
+  session
+    .command("leave <sessionId>")
+    .description("Leave a session")
+    .option("--agent <id>", "Agent id to unregister", "cli-user")
+    .option("--reason <reason>", "Leave reason", "manual")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .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 = normalizeAgentId(options.agent, "cli-user");
+      const left = await unregisterAgent(normalizedSessionId, agentId, {
+        reason: options.reason || "manual",
+        targetPath,
+      });
+      const payload = {
+        command: "session leave",
+        targetPath,
+        sessionId: normalizedSessionId,
+        agentId: left.agentId,
+        reason: left.leaveReason,
+        leftAt: left.leftAt,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Left session ${normalizedSessionId}`));
+      console.log(pc.gray(`agent=${left.agentId} reason=${left.leaveReason}`));
+    });
+
+  session
+    .command("list")
+    .description("List active sessions")
+    .option("--path <path>", "Workspace path for sessions", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const sessions = await listActiveSessions({
+        targetPath,
+      });
+      const payload = {
+        command: "session list",
+        targetPath,
+        count: sessions.length,
+        sessions,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      if (sessions.length === 0) {
+        console.log(pc.yellow("No active sessions."));
+        return;
+      }
+      for (const item of sessions) {
+        console.log(
+          `${item.sessionId} status=${item.status} created_at=${item.createdAt} expires_at=${item.expiresAt}`
+        );
+      }
+    });
+
+  session
+    .command("kill")
+    .description("Kill a single agent or all agents in a session")
+    .option("--agent <id>", "Specific agent id to stop")
+    .option("--all", "Kill every known agent in the session")
+    .option("--session <id>", "Session id")
+    .option("--id <sessionId>", "Deprecated alias for --session")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--reason <reason>", "Kill reason code", "manual_stop")
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const sessionId = resolveSessionIdOption(options);
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const reason = normalizeString(options.reason) || "manual_stop";
+      const requestedAgent = normalizeString(options.agent).toLowerCase();
+
+      if (!options.all && !requestedAgent) {
+        throw new Error("session kill requires --agent <id> or --all.");
+      }
+
+      const startedAt = Date.now();
+      const discoveredAgents = await listAgents(sessionId, {
+        targetPath,
+        includeInactive: false,
+      });
+      const agentsToKill = new Set();
+      if (options.all) {
+        agentsToKill.add("senti");
+        agentsToKill.add("scope-engine");
+        for (const agent of discoveredAgents) {
+          const agentId = normalizeString(agent.agentId).toLowerCase();
+          if (agentId) {
+            agentsToKill.add(agentId);
+          }
+        }
+      } else {
+        agentsToKill.add(requestedAgent);
+      }
+
+      const results = [];
+      let runtimeStops = 0;
+      let scopeStops = 0;
+      let leaseRevocations = 0;
+      let anyStopped = false;
+
+      for (const agentId of agentsToKill) {
+        let stopped = false;
+        let stopDetails = {};
+        if (agentId === "senti") {
+          const stopResult = await stopSenti(sessionId, {
+            targetPath,
+            reason,
+          });
+          runtimeStops += Number(stopResult?.runtimeStopSummary?.stoppedCount || 0);
+          stopped = Boolean(stopResult?.stopped);
+          stopDetails = {
+            runtimeStops: Number(stopResult?.runtimeStopSummary?.stoppedCount || 0),
+            scopeStops: 0,
+          };
+        } else if (agentId === "scope-engine") {
+          const stopResult = await stopScopeEngine({
+            targetPath,
+            sessionId,
+            reason,
+          });
+          scopeStops += Number(stopResult?.count || 0);
+          stopped = Boolean(stopResult?.stopped);
+          stopDetails = {
+            runtimeStops: 0,
+            scopeStops: Number(stopResult?.count || 0),
+          };
+        } else {
+          try {
+            await unregisterAgent(sessionId, agentId, {
+              reason: "killed",
+              targetPath,
+            });
+            stopped = true;
+          } catch {
+            stopped = false;
+          }
+          if (stopped) {
+            await emitAgentKilledEvent(sessionId, agentId, {
+              targetPath,
+              reason,
+              leaseRevocations: 0,
+            });
+          }
+          stopDetails = {
+            runtimeStops: 0,
+            scopeStops: 0,
+          };
+        }
+
+        const releasedCount = await revokeAgentLeases(sessionId, agentId, {
+          targetPath,
+          reason: `agent_killed:${reason}`,
+        });
+        leaseRevocations += releasedCount;
+        anyStopped = anyStopped || stopped;
+
+        results.push({
+          agentId,
+          stopped,
+          runtimeStops: stopDetails.runtimeStops,
+          scopeStops: stopDetails.scopeStops,
+          leaseRevocations: releasedCount,
+        });
+      }
+
+      const durationMs = Date.now() - startedAt;
+      const primaryAgentId = !options.all ? requestedAgent : null;
+      const payload = {
+        command: "session kill",
+        targetPath,
+        durationMs,
+        sessionId,
+        agentId: primaryAgentId,
+        all: Boolean(options.all),
+        reason,
+        stopped: anyStopped,
+        runtimeStops,
+        scopeStops,
+        leaseRevocations,
+        results,
+      };
+
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      if (payload.stopped) {
+        console.log(pc.bold("Kill complete"));
+      } else {
+        console.log(pc.yellow(`No active target found in session ${sessionId}.`));
+      }
+      console.log(
+        pc.gray(
+          `session=${sessionId} runtime_stops=${runtimeStops} scope_stops=${scopeStops} lease_revocations=${leaseRevocations}`
+        )
+      );
+      console.log(`stopped=${payload.stopped} reason=${reason} duration_ms=${durationMs}`);
+    });
+}

package/src/commands/spec.js

@@ -91,6 +91,60 @@ function resolveSpecArtifactPath(targetPath, explicitPath) {
   throw new Error("No spec artifact found. Generate one with 'spec generate' or pass --file.");
 }
 
+async function readAgentsMarkdown(targetPath) {
+  const agentsPath = path.join(targetPath, "AGENTS.md");
+  try {
+    return await fsp.readFile(agentsPath, "utf-8");
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function isSessionMetadataActive(metadata = {}, nowEpoch = Date.now()) {
+  const status = String(metadata.status || "").trim().toLowerCase();
+  if (status === "expired" || status === "archived") {
+    return false;
+  }
+  const expiryEpoch = Date.parse(String(metadata.expiresAt || ""));
+  if (!Number.isFinite(expiryEpoch)) {
+    return false;
+  }
+  return expiryEpoch > nowEpoch;
+}
+
+async function detectSessionActive(targetPath) {
+  const sessionsRoot = path.join(targetPath, ".sentinelayer", "sessions");
+  let entries = [];
+  try {
+    entries = await fsp.readdir(sessionsRoot, { withFileTypes: true });
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+  const nowEpoch = Date.now();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const metadataPath = path.join(sessionsRoot, entry.name, "metadata.json");
+    try {
+      const raw = await fsp.readFile(metadataPath, "utf-8");
+      const metadata = JSON.parse(raw);
+      if (isSessionMetadataActive(metadata, nowEpoch)) {
+        return true;
+      }
+    } catch {
+      // Ignore malformed or missing metadata for one session and continue scanning.
+    }
+  }
+  return false;
+}
+
 function estimateTokenCount(text) {
   const normalized = String(text || "");
   if (!normalized) {
@@ -466,6 +520,8 @@ export function registerSpecCommand(program) {
           refresh: Boolean(options.refresh),
         });
         const ingest = ingestResolution.ingest;
+        const agentsMarkdown = await readAgentsMarkdown(targetPath);
+        const sessionActive = await detectSessionActive(targetPath);
         const explicitProjectType = parseProjectTypeOption(options.projectType);
         const resolvedProjectType = resolveProjectType({
           projectType: explicitProjectType,
@@ -479,6 +535,8 @@ export function registerSpecCommand(program) {
           ingest,
           projectPath: targetPath,
           projectType: resolvedProjectType,
+          agentsMarkdown,
+          sessionActive,
         });
 
         progress.update(65, "spec generate: optional AI refinement");
@@ -579,6 +637,8 @@ export function registerSpecCommand(program) {
           refresh: Boolean(options.refresh),
         });
         const ingest = ingestResolution.ingest;
+        const agentsMarkdown = await readAgentsMarkdown(targetPath);
+        const sessionActive = await detectSessionActive(targetPath);
         const explicitProjectType = parseProjectTypeOption(options.projectType);
         const inferredProjectType = inferProjectTypeFromSpecMarkdown(existingMarkdown);
         const resolvedProjectType = resolveProjectType({
@@ -592,6 +652,8 @@ export function registerSpecCommand(program) {
           ingest,
           projectPath: targetPath,
           projectType: resolvedProjectType,
+          agentsMarkdown,
+          sessionActive,
         });
 
         progress.update(55, "spec regenerate: preserving manual sections");

package/src/commands/watch.js

@@ -12,6 +12,7 @@ import {
   resolveActiveAuthSession,
 } from "../auth/service.js";
 import { resolveOutputRoot } from "../config/service.js";
+import { authLoginHint } from "../ui/command-hints.js";
 
 const TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "cancelled"]);
 
@@ -369,7 +370,7 @@ export function registerWatchCommand(program) {
       }
 
       if (!session || !session.token) {
-        throw new Error("No active auth token found. Run `sl auth login` first.");
+        throw new Error(`No active auth token found. Run \`${authLoginHint()}\` first.`);
       }
 
       const startedAtEpoch = Date.now();
@@ -446,7 +447,7 @@ export function registerWatchCommand(program) {
         }
       } catch (error) {
         if (error instanceof SentinelayerApiError && (error.status === 401 || error.status === 403)) {
-          throw new Error("Authentication failed while watching runtime events. Run `sl auth login`.");
+          throw new Error(`Authentication failed while watching runtime events. Run \`${authLoginHint()}\`.`);
         }
         throw new Error(formatApiError(error));
       }