sentinelayer-cli 0.8.11 → 0.9.0

package/src/session/senti-naming.js

@@ -129,6 +129,42 @@ export function isAnonymousAgent(agent = {}) {
   return idAnonymous || modelAnonymous;
 }
 
+/**
+ * Derive a deterministic session title from a workspace path + clock.
+ *
+ * Carter's complaint: every CLI invocation minted an unnamed session, so the
+ * web sidebar filled with hundreds of "<null>" rows that all looked like the
+ * same chat re-created. The fix: when the caller doesn't pass `--title`, give
+ * the session a stable label based on the codebase basename + today's date in
+ * UTC, e.g. `create-sentinelayer-2026-04-28`.
+ *
+ * - Basename only (we never leak the absolute path).
+ * - Sanitized to `[a-z0-9-]` so the title is URL-safe + dashboard-friendly.
+ * - Date is UTC ISO short form (YYYY-MM-DD) for reproducibility regardless of
+ *   the host timezone.
+ * - Falls back to `session-<date>` if the path has no usable basename.
+ *
+ * @param {string} targetPath
+ * @param {{now?: Date}} [options]
+ * @returns {string}
+ */
+export function deriveSessionTitle(targetPath, { now = new Date() } = {}) {
+  const raw = String(targetPath || "").trim();
+  // Use forward slashes consistently — Windows paths come through with
+  // backslashes from path.resolve. We don't import the `path` module here
+  // to keep this function pure + cheap to test.
+  const last = raw.split(/[/\\]+/).filter(Boolean).pop() || "";
+  const slug = last
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  const stamp = (now instanceof Date && !Number.isNaN(now.getTime()) ? now : new Date())
+    .toISOString()
+    .slice(0, 10);
+  return slug ? `${slug}-${stamp}` : `session-${stamp}`;
+}
+
 /**
  * Build the payload Senti emits as `agent_identified` when it has
  * stepped in to name a participant. Consumers (CLI / web) render it

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/session/sync.js

@@ -407,6 +407,17 @@ export async function syncSessionEventToApi(
     return { synced: false, reason: "invalid_input" };
   }
 
+  // Test-fixture leak guard. Tests in this repo (and downstream consumers)
+  // create + tear down sessions using a temp workspace; on a developer
+  // machine those calls inherit the user's stored auth and silently posted
+  // hundreds of orphan rooms to prod (Carter saw ~200 "<null>" sessions).
+  // Honoring SENTINELAYER_SKIP_REMOTE_SYNC=1 keeps everything local while
+  // still exercising the appendToStream + agent_join code paths the tests
+  // care about. Local NDJSON durability is unaffected.
+  if (String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1") {
+    return { synced: false, reason: "remote_sync_disabled_env" };
+  }
+
   const normalizedNowMs = Number(nowMs()) || Date.now();
   if (isCircuitOpen(outboundCircuit, normalizedNowMs)) {
     return { synced: false, reason: "circuit_breaker_open" };
@@ -501,6 +512,13 @@ async function syncSessionAuxPayload(
     return { synced: false, reason: "invalid_input" };
   }
 
+  // Same test-fixture leak guard as syncSessionEventToApi — keep parity
+  // so neither the event channel nor the metadata/error channels can
+  // exfiltrate a test session into prod when the env flag is set.
+  if (String(process.env.SENTINELAYER_SKIP_REMOTE_SYNC || "").trim() === "1") {
+    return { synced: false, reason: "remote_sync_disabled_env" };
+  }
+
   const normalizedNowMs = Number(nowMs()) || Date.now();
   if (isCircuitOpen(outboundCircuit, normalizedNowMs)) {
     return { synced: false, reason: "circuit_breaker_open" };
@@ -1034,6 +1052,11 @@ export function resetSessionSyncStateForTests() {
   inboundCircuit.openedAtMs = 0;
   sessionIngestWindowBySessionId.clear();
   humanRelayWindowBySessionId.clear();
+  // Tests that exercise the network path explicitly need the
+  // SENTINELAYER_SKIP_REMOTE_SYNC guard off — otherwise the function
+  // short-circuits before the mocked fetchImpl is ever called. Tests that
+  // want the guard on can re-set the env after resetting.
+  delete process.env.SENTINELAYER_SKIP_REMOTE_SYNC;
 }
 
 export {

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({