sentinelayer-cli 0.8.12 → 0.9.0

package/src/session/listener.js

@@ -0,0 +1,236 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+import { pollSessionEvents } from "./sync.js";
+import { readSyncCursor, writeSyncCursor } from "./sync-cursor.js";
+
+const BROADCAST_RECIPIENTS = new Set([
+  "*",
+  "all",
+  "broadcast",
+  "everyone",
+  "anyone",
+  "agents",
+  "all-agents",
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeComparableId(value) {
+  return normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function normalizePositiveInteger(value, fallbackValue) {
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) return fallbackValue;
+  return Math.floor(normalized);
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function addRecipientValue(values, value) {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    for (const item of value) addRecipientValue(values, item);
+    return;
+  }
+  if (isPlainObject(value)) {
+    addRecipientValue(values, value.id || value.agentId || value.name);
+    return;
+  }
+  const raw = normalizeString(value);
+  if (!raw) return;
+  for (const token of raw.split(/[\s,;]+/g)) {
+    const normalized = normalizeString(token);
+    if (normalized) values.push(normalized);
+  }
+}
+
+export function collectSessionEventRecipients(event = {}) {
+  const values = [];
+  if (!isPlainObject(event)) return values;
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  for (const source of [
+    event.to,
+    event.recipient,
+    event.recipients,
+    event.targetAgent,
+    event.targetAgentId,
+    payload.to,
+    payload.recipient,
+    payload.recipients,
+    payload.targetAgent,
+    payload.targetAgentId,
+  ]) {
+    addRecipientValue(values, source);
+  }
+  return values;
+}
+
+export function eventMatchesAgent(event = {}, agentId = "") {
+  if (!isPlainObject(event)) return false;
+  const normalizedAgentId = normalizeComparableId(agentId);
+  if (!normalizedAgentId) return false;
+
+  const payload = isPlainObject(event.payload) ? event.payload : {};
+  if (event.broadcast === true || payload.broadcast === true) return true;
+
+  const recipients = collectSessionEventRecipients(event);
+  if (recipients.length === 0) return true;
+
+  for (const recipient of recipients) {
+    const rawRecipient = normalizeString(recipient).toLowerCase();
+    if (BROADCAST_RECIPIENTS.has(rawRecipient)) return true;
+    const normalizedRecipient = normalizeComparableId(recipient);
+    if (!normalizedRecipient) continue;
+    if (BROADCAST_RECIPIENTS.has(normalizedRecipient)) return true;
+    if (normalizedRecipient === normalizedAgentId) return true;
+  }
+  return false;
+}
+
+export function listenCursorSuffix(agentId = "") {
+  return `listen-${normalizeComparableId(agentId) || "agent"}`;
+}
+
+async function defaultSleep(ms, { signal } = {}) {
+  await delay(ms, undefined, { signal });
+}
+
+function shouldAbort(error, signal) {
+  return Boolean(signal?.aborted || error?.name === "AbortError" || error?.code === "ABORT_ERR");
+}
+
+function cursorFromEvents(events = [], fallbackCursor = null) {
+  let cursor = normalizeString(fallbackCursor) || null;
+  for (const event of events) {
+    const candidate = normalizeString(event?.cursor);
+    if (candidate) cursor = candidate;
+  }
+  return cursor;
+}
+
+function eventTimestampMs(event = {}) {
+  for (const key of ["ts", "timestamp", "createdAt", "at"]) {
+    const epoch = Date.parse(normalizeString(event?.[key]));
+    if (Number.isFinite(epoch)) return epoch;
+  }
+  return 0;
+}
+
+/**
+ * Poll session events in the background and emit only events addressed to
+ * the current agent or broadcast to everyone. The loop advances its cursor
+ * across non-matching events so direct listeners do not replay unrelated
+ * traffic forever.
+ */
+export async function listenSessionEvents({
+  sessionId,
+  targetPath = process.cwd(),
+  agentId = "cli-user",
+  intervalSeconds = 60,
+  limit = 200,
+  since = undefined,
+  replay = false,
+  maxPolls = null,
+  signal,
+  onEvent = async () => {},
+  onError = async () => {},
+  _poll = pollSessionEvents,
+  _readCursor = readSyncCursor,
+  _writeCursor = writeSyncCursor,
+  _sleep = defaultSleep,
+  _nowMs = Date.now,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedAgentId = normalizeComparableId(agentId) || "cli-user";
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+
+  const cursorSuffix = listenCursorSuffix(normalizedAgentId);
+  let cursor =
+    typeof since === "string" || since === null
+      ? normalizeString(since) || null
+      : await _readCursor(normalizedSessionId, { targetPath, suffix: cursorSuffix });
+  let primed = Boolean(cursor) || Boolean(replay);
+  let pollCount = 0;
+  let emitted = 0;
+  let matched = 0;
+  let persistedCursor = false;
+  let lastReason = "";
+  const maxPollCount = normalizePositiveInteger(maxPolls, 0);
+  const pollLimit = normalizePositiveInteger(limit, 200);
+  const sleepMs = Math.max(1, normalizePositiveInteger(intervalSeconds, 60)) * 1000;
+  const startedAtMs = Number(_nowMs()) || Date.now();
+
+  while (!signal?.aborted) {
+    pollCount += 1;
+    const result = await _poll(normalizedSessionId, {
+      targetPath,
+      since: cursor,
+      limit: pollLimit,
+    });
+
+    if (result?.ok) {
+      lastReason = "";
+      const events = Array.isArray(result.events) ? result.events : [];
+      const shouldEmitBatch = primed || Boolean(replay);
+      for (const event of events) {
+        if (!eventMatchesAgent(event, normalizedAgentId)) continue;
+        matched += 1;
+        if (!shouldEmitBatch && eventTimestampMs(event) < startedAtMs) continue;
+        await onEvent(event);
+        emitted += 1;
+      }
+
+      const nextCursor = normalizeString(result.cursor) || cursorFromEvents(events, cursor);
+      if (nextCursor && nextCursor !== cursor) {
+        const writeResult = await _writeCursor(normalizedSessionId, nextCursor, {
+          targetPath,
+          suffix: cursorSuffix,
+        }).catch(() => null);
+        persistedCursor = Boolean(writeResult?.written) || persistedCursor;
+        cursor = nextCursor;
+      }
+      primed = true;
+    } else {
+      lastReason = normalizeString(result?.reason) || "poll_failed";
+      await onError({
+        ok: false,
+        reason: lastReason,
+        cursor: result?.cursor || cursor || null,
+      });
+    }
+
+    if (maxPollCount > 0 && pollCount >= maxPollCount) break;
+    try {
+      await _sleep(sleepMs, { signal });
+    } catch (error) {
+      if (shouldAbort(error, signal)) break;
+      throw error;
+    }
+  }
+
+  return {
+    ok: true,
+    sessionId: normalizedSessionId,
+    agentId: normalizedAgentId,
+    cursor,
+    cursorSuffix,
+    pollCount,
+    matched,
+    emitted,
+    persistedCursor,
+    reason: lastReason,
+  };
+}

package/src/session/setup-guides.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import process from "node:process";
 
 import { buildAgentsSessionGuideContent } from "../legacy-cli.js";
+import { renderCoordinationBulletList } from "./coordination-guidance.js";
 import { getSession } from "./store.js";
 
 const SECTION_START_MARKER = "<!-- SENTINELAYER_SESSION_COORDINATION:START -->";
@@ -26,21 +27,8 @@ function buildSessionCoordinationSection() {
   return `${SECTION_START_MARKER}
 ${SECTION_HEADING}
 
-### Before You Start
-- Check for active sessions: \`sl session list\`
-- Join if one exists: \`sl session join <id> --name <your-name>\`
-- Read recent context: \`sl session read <id> --tail 20\`
-
-### While Working
-- Emit status every 5 min: \`sl session say <id> "status: <what you're doing>"\`
-- Lock files before editing: \`sl session say <id> "lock: <file> - <intent>"\`
-- Unlock when done: \`sl session say <id> "unlock: <file> - done"\`
-- Post findings: \`sl session say <id> "finding: [P2] <title> in <file>:<line>"\`
-
-### On Problems
-- Unexpected file change? Ask: \`sl session say <id> "help: unexpected change in <file>"\`
-- Need another agent's work? Request: \`sl session say <id> "handoff: @<agent> <description>"\`
-- Found issues for others? Assign: \`sl session say <id> "assign: @<agent> <task>"\`
+### Required Etiquette
+${renderCoordinationBulletList()}
 
 ### What Not To Do
 - Do not break your autonomous loop on unexpected file changes; ask in session first.

package/src/session/store.js

@@ -43,6 +43,21 @@ function normalizeNonNegativeInteger(value, fallbackValue = 0) {
   return Math.floor(normalized);
 }
 
+function normalizeCreateSessionId(value) {
+  const normalized = normalizeString(value);
+  if (!normalized) return randomUUID();
+  if (
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.includes("/") ||
+    normalized.includes("\\") ||
+    normalized.includes("..")
+  ) {
+    throw new Error("sessionId must not contain path traversal segments.");
+  }
+  return normalized;
+}
+
 function normalizeIsoTimestamp(value, fallbackIso = new Date().toISOString()) {
   const normalized = normalizeString(value);
   if (!normalized) {
@@ -148,7 +163,7 @@ function toRelativePosix(baseDir, absolutePath) {
 
 function normalizeDateKeyFromCloseoutPath(closeoutPath = "", fallbackIso = new Date().toISOString()) {
   const normalized = toPosixPath(closeoutPath);
-  const match = /\/observability\/(\d{4}-\d{2}-\d{2})\//.exec(`/${normalized}`);
+  const match = /\/observability\/(\d{4}-\d{2}-\d{2})\//.exec("/" + normalized);
   if (match) {
     return match[1];
   }
@@ -330,6 +345,7 @@ function normalizeMetadata(raw = {}, { sessionId, targetPath, nowIso } = {}) {
     createdAt,
     updatedAt: normalizeIsoTimestamp(raw.updatedAt, nowIso),
     expiresAt,
+    title: normalizeString(raw.title) || null,
     ttlSeconds,
     renewalCount: Math.max(0, Number(raw.renewalCount || 0)),
     maxLifetimeSeconds: normalizePositiveInteger(raw.maxLifetimeSeconds, MAX_SESSION_LIFETIME_SECONDS),
@@ -364,7 +380,10 @@ function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString())
     metadataPath: paths.metadataPath,
     streamPath: paths.streamPath,
     createdAt: metadata.createdAt,
+    updatedAt: metadata.updatedAt,
     expiresAt: metadata.expiresAt,
+    lastInteractionAt: metadata.lastInteractionAt,
+    title: metadata.title,
     elapsedTimer: buildElapsedTimer(metadata.createdAt, nowIso),
     renewalCount: metadata.renewalCount,
     status: metadata.status,
@@ -406,11 +425,22 @@ export async function createSession({
   targetPath = process.cwd(),
   ttlSeconds = DEFAULT_TTL_SECONDS,
   template = null,
+  sessionId: requestedSessionId = "",
+  title = "",
+  createdAt = "",
+  expiresAt = "",
+  lastInteractionAt = "",
 } = {}) {
   const resolvedTargetPath = path.resolve(String(targetPath || "."));
   const normalizedTtlSeconds = normalizePositiveInteger(ttlSeconds, DEFAULT_TTL_SECONDS);
-  const sessionId = randomUUID();
+  const sessionId = normalizeCreateSessionId(requestedSessionId);
   const nowIso = new Date().toISOString();
+  const createdIso = normalizeIsoTimestamp(createdAt, nowIso);
+  const expiresIso = normalizeIsoTimestamp(
+    expiresAt,
+    toIsoAfterSeconds(createdIso, normalizedTtlSeconds)
+  );
+  const interactionIso = normalizeIsoTimestamp(lastInteractionAt, createdIso);
   const paths = resolveSessionPaths(sessionId, { targetPath: resolvedTargetPath });
   const codebaseContext = await collectSessionCodebaseContext(resolvedTargetPath);
 
@@ -419,14 +449,15 @@ export async function createSession({
       schemaVersion: SESSION_SCHEMA_VERSION,
       sessionId,
       targetPath: resolvedTargetPath,
-      createdAt: nowIso,
+      createdAt: createdIso,
       updatedAt: nowIso,
-      expiresAt: toIsoAfterSeconds(nowIso, normalizedTtlSeconds),
+      expiresAt: expiresIso,
+      title: normalizeString(title) || null,
       ttlSeconds: normalizedTtlSeconds,
       renewalCount: 0,
       maxLifetimeSeconds: MAX_SESSION_LIFETIME_SECONDS,
       status: SESSION_STATUS_ACTIVE,
-      lastInteractionAt: nowIso,
+      lastInteractionAt: interactionIso,
       expiredAt: null,
       archivedAt: null,
       s3Path: null,
@@ -449,6 +480,24 @@ export async function createSession({
   return buildSessionPayload(metadata, paths, nowIso);
 }
 
+export async function updateSessionTitle(
+  sessionId,
+  { targetPath = process.cwd(), title = "" } = {}
+) {
+  const loaded = await loadMetadata(sessionId, { targetPath });
+  if (!loaded) {
+    return null;
+  }
+  const nowIso = new Date().toISOString();
+  const metadata = {
+    ...loaded.metadata,
+    title: normalizeString(title) || null,
+    updatedAt: nowIso,
+  };
+  const saved = await saveMetadata(metadata, loaded.paths);
+  return buildSessionPayload(saved, loaded.paths, nowIso);
+}
+
 export async function getSession(sessionId, { targetPath = process.cwd() } = {}) {
   const loaded = await loadMetadata(sessionId, { targetPath });
   if (!loaded) {

package/src/spec/generator.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 
+import { getCoordinationEtiquetteItems } from "../session/coordination-guidance.js";
 import { getDefaultTemplate, getTemplateById } from "./templates.js";
 
 const VALID_PROJECT_TYPES = new Set(["greenfield", "add_feature", "bugfix"]);
@@ -494,7 +495,11 @@ function shouldIncludeCoordinationPhase({
   description = "",
   agentsMarkdown = "",
   sessionActive = false,
+  sessionToolsAvailable = true,
 } = {}) {
+  if (sessionToolsAvailable === true) {
+    return true;
+  }
   if (sessionActive === true) {
     return true;
   }
@@ -507,16 +512,7 @@ function shouldIncludeCoordinationPhase({
 function buildCoordinationPhase(phaseNumber, previousPhaseTitle = "") {
   return {
     title: `Phase ${phaseNumber}: Multi-Agent Coordination Protocol`,
-    items: [
-      "Check for active sessions: `sl session list`.",
-      "If a session exists, join it: `sl session join <id> --name <your-name> --role coder`.",
-      "Emit status updates every 5 minutes: `sl session say <id> \"status: <what you're doing>\"`.",
-      "Before modifying a shared file, check recent session activity for that file.",
-      "On unexpected file changes, ask in-session instead of stopping: `sl session say <id> \"help: <question>\"`.",
-      "Post findings in-session: `sl session say <id> \"finding: [P2] <title> in <file>:<line>\"`.",
-      "On completion, update `tasks/todo.md` and emit completion status in-session.",
-      "Leave the session when done: `sl session leave <id>`.",
-    ],
+    items: getCoordinationEtiquetteItems(),
     dependencies: previousPhaseTitle ? [previousPhaseTitle] : [],
     effort: "4-8 hours",
     acceptanceCriteria: [
@@ -535,6 +531,7 @@ export function generateSpecMarkdown({
   projectType,
   agentsMarkdown = "",
   sessionActive = false,
+  sessionToolsAvailable = true,
   generatedAt = new Date().toISOString(),
 } = {}) {
   const resolvedTemplate = template || getDefaultTemplate();
@@ -566,6 +563,7 @@ export function generateSpecMarkdown({
       description,
       agentsMarkdown,
       sessionActive,
+      sessionToolsAvailable,
     })
   ) {
     phases.push(buildCoordinationPhase(phases.length + 1, phases[phases.length - 1]?.title || ""));

package/src/swarm/registry.js

@@ -204,6 +204,26 @@ const BUILTIN_SWARM_AGENTS = Object.freeze([
     evidenceRequirements: ["dependency_refs", "version_risks"],
     escalationTargets: ["security", "release"],
   },
+  {
+    id: "devtestbot",
+    persona: "AIdenID devTestBot",
+    role: "specialist",
+    domain: "Browser/System E2E",
+    tools: ["devtestbot.run_session"],
+    permissionMode: "runtime-readonly",
+    maxTurns: 8,
+    confidenceFloor: 0.8,
+    allowedPaths: ["."],
+    networkMode: "enabled",
+    defaultBudget: {
+      maxCostUsd: 1.5,
+      maxOutputTokens: 6000,
+      maxRuntimeMs: 600000,
+      maxToolCalls: 40,
+    },
+    evidenceRequirements: ["artifact_path", "runtime_evidence", "reproduction", "confidence"],
+    escalationTargets: ["testing", "frontend", "reliability"],
+  },
   {
     id: "frontend",
     persona: "Jules Tanaka",

package/src/swarm/runtime.js

@@ -10,6 +10,13 @@ function normalizeString(value) {
   return String(value || "").trim();
 }
 
+function sanitizeRuntimeError(error) {
+  return String(error?.message || error || "Runtime failed.")
+    .replace(/\b(?:authorization|cookie|token|secret|password|otp|reset)\s*[:=]\s*["']?[^"'\s&]+/gi, (match) =>
+      match.replace(/[:=]\s*["']?.*$/u, "=[REDACTED]")
+    );
+}
+
 function formatTimestampToken() {
   const now = new Date();
   const pad = (value) => String(value).padStart(2, "0");
@@ -298,6 +305,9 @@ export async function runSwarmRuntime({
   execute = false,
   maxSteps = 20,
   startUrl = "about:blank",
+  identityId = "",
+  devTestBotScope = "",
+  devTestBotRunSession = null,
   playbookActions = [],
   outputDir = "",
   env,
@@ -321,6 +331,9 @@ export async function runSwarmRuntime({
   const runtimeRunDirectory = path.join(resolvedOutputRoot, "swarms", runId);
   const runStartedAt = Date.now();
   const events = [];
+  const findings = [];
+  const artifactBundles = [];
+  const devTestBotRuns = [];
   let step = 0;
 
   const usage = {
@@ -409,7 +422,128 @@ export async function runSwarmRuntime({
         })
       );
 
-      if (normalizedEngine === "mock" || !execute) {
+      if (assignment.agentId === "devtestbot") {
+        const scope = normalizeString(devTestBotScope || plan.scenario || "smoke") || "smoke";
+        const toolInput = {
+          scope,
+          identityId: normalizeString(identityId),
+          baseUrl: normalizeString(startUrl),
+          recordVideo: Boolean(execute),
+          execute: Boolean(execute),
+          targetPath: normalizedTargetPath,
+          outputRoot: resolvedOutputRoot,
+          outputDir: path.join(runtimeRunDirectory, "devtestbot", assignment.assignmentId),
+          runId: `${runId}-${assignment.assignmentId}`,
+        };
+
+        usage.toolCalls += 1;
+        usage.outputTokens += estimateTokens(`devtestbot.run_session:${scope}:${Boolean(execute)}`);
+        step += 1;
+        events.push(
+          createEvent({
+            runId,
+            step,
+            eventType: "tool_call",
+            agentId: assignment.agentId,
+            message: "devtestbot.run_session started",
+            metadata: {
+              tool: "devtestbot.run_session",
+              scope,
+              identityId: toolInput.identityId || null,
+              baseUrl: toolInput.baseUrl,
+              execute: toolInput.execute,
+              recordVideo: toolInput.recordVideo,
+            },
+            usage,
+          })
+        );
+
+        try {
+          const runner = devTestBotRunSession || (await import("../agents/devtestbot/tool.js")).runDevTestBotSession;
+          const result = await runner(toolInput, {
+            targetPath: normalizedTargetPath,
+            outputRoot: resolvedOutputRoot,
+            runId: toolInput.runId,
+            execute: Boolean(execute),
+            env,
+          });
+          const resultFindings = Array.isArray(result.findings) ? result.findings : [];
+          findings.push(...resultFindings);
+          if (result.artifactBundle) {
+            artifactBundles.push(result.artifactBundle);
+          }
+          devTestBotRuns.push({
+            assignmentId: assignment.assignmentId,
+            runId: result.runId || toolInput.runId,
+            completed: Boolean(result.completed),
+            dryRun: Boolean(result.dryRun),
+            findingCount: resultFindings.length,
+            artifactBundle: result.artifactBundle || null,
+          });
+          usage.outputTokens += estimateTokens(
+            JSON.stringify({
+              findingCount: resultFindings.length,
+              artifactBundle: result.artifactBundle ? "present" : "missing",
+            })
+          );
+          step += 1;
+          events.push(
+            createEvent({
+              runId,
+              step,
+              eventType: "tool_result",
+              agentId: assignment.agentId,
+              message: "devtestbot.run_session completed",
+              metadata: {
+                tool: "devtestbot.run_session",
+                success: true,
+                dryRun: Boolean(result.dryRun),
+                findingCount: resultFindings.length,
+                artifactBundle: result.artifactBundle || null,
+              },
+              usage,
+            })
+          );
+          for (const finding of resultFindings) {
+            step += 1;
+            events.push(
+              createEvent({
+                runId,
+                step,
+                eventType: "finding",
+                agentId: assignment.agentId,
+                message: normalizeString(finding.title || "devTestBot finding"),
+                metadata: {
+                  finding,
+                },
+                usage,
+              })
+            );
+          }
+        } catch (error) {
+          stop = {
+            stopClass: error?.code || "DEVTESTBOT_RUN_FAILED",
+            reason: sanitizeRuntimeError(error),
+            blocking: true,
+          };
+          step += 1;
+          events.push(
+            createEvent({
+              runId,
+              step,
+              eventType: "agent_error",
+              agentId: assignment.agentId,
+              message: stop.reason,
+              metadata: {
+                tool: "devtestbot.run_session",
+                stopClass: stop.stopClass,
+              },
+              usage,
+            })
+          );
+          break;
+        }
+      } else if (normalizedEngine === "mock" || !execute) {
         usage.toolCalls += 1;
         usage.outputTokens += estimateTokens(`mock:${assignment.agentId}`);
         step += 1;
@@ -558,6 +692,10 @@ export async function runSwarmRuntime({
     usage,
     eventCount: events.length,
     selectedAgents: Array.isArray(plan.selectedAgents) ? [...plan.selectedAgents] : [],
+    findingCount: findings.length,
+    findings,
+    artifactBundles,
+    devTestBotRuns,
   };
 
   return writeRuntimeArtifacts({