sentinelayer-cli 0.8.0 → 0.8.1

package/src/coord/index.js

@@ -0,0 +1,35 @@
+// Barrel export for the .sentinel cross-persona handshake (#A9, spec §5.6).
+// Callers should import from "src/coord" rather than reaching into individual
+// modules so we can reshape internals without rippling through the codebase.
+
+export {
+  DEFAULT_TTL_S,
+  LOCK_SCHEMA_VERSION,
+  MAX_TTL_S,
+  MIN_TTL_S,
+  PERSONA_PRIORITY,
+  checkLock,
+  detectDeadlock,
+  hashLockKey,
+  listActiveLocks,
+  listWaiters,
+  normalizeLockPath,
+  outranks,
+  priorityIndex,
+  releaseLock,
+  requestLock,
+} from "./handshake.js";
+
+export { appendEvent, readEvents, KNOWN_EVENT_TYPES } from "./events-log.js";
+
+export { findCycles, tarjanSCC } from "./tarjan.js";
+
+export { lowestPriorityAgent } from "./priority.js";
+
+export {
+  lockFileFor,
+  resolveEventsPath,
+  resolveLocksDir,
+  resolveSentinelDir,
+  resolveWaitsPath,
+} from "./paths.js";

package/src/coord/paths.js

@@ -0,0 +1,84 @@
+// Filesystem layout for the cross-persona LOCK/ACK/RELEASE handshake (#A9).
+//
+// All state lives under `.sentinel/` at the target repo root. This is
+// intentionally *not* `.sentinelayer/sessions/<id>/` (which scopes file locks
+// to a single Senti session) because the handshake is a cross-session
+// coordination primitive: when Omar Gate 2.0 verifies a PR, it reads the
+// same lock files the personas wrote without needing to know their session id.
+
+import crypto from "node:crypto";
+import path from "node:path";
+import process from "node:process";
+
+const SENTINEL_ROOT = ".sentinel";
+const LOCKS_SUBDIR = "locks";
+const EVENTS_FILE = "events.jsonl";
+const WAITS_FILE = "waits.json";
+const MUTEX_LOCK = ".lock-mutex.lock";
+const EVENTS_LOCK = ".events.lock";
+const WAITS_LOCK = ".waits.lock";
+
+export function resolveSentinelDir({ targetPath = process.cwd() } = {}) {
+  return path.join(path.resolve(String(targetPath || ".")), SENTINEL_ROOT);
+}
+
+export function resolveLocksDir({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), LOCKS_SUBDIR);
+}
+
+export function resolveEventsPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), EVENTS_FILE);
+}
+
+export function resolveWaitsPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), WAITS_FILE);
+}
+
+export function resolveMutexLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), MUTEX_LOCK);
+}
+
+export function resolveEventsLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), EVENTS_LOCK);
+}
+
+export function resolveWaitsLockPath({ targetPath = process.cwd() } = {}) {
+  return path.join(resolveSentinelDir({ targetPath }), WAITS_LOCK);
+}
+
+// Normalize the caller's intended file path into a stable, repo-relative,
+// posix-style string. Absolute paths are relativized against targetPath so
+// the same file produces the same hash across macOS/Linux/Windows workers.
+export function normalizeLockPath(filePath, { targetPath = process.cwd() } = {}) {
+  const raw = String(filePath || "").trim();
+  if (!raw) {
+    throw new Error("path is required.");
+  }
+  const resolvedTarget = path.resolve(String(targetPath || "."));
+  let normalized;
+  if (path.isAbsolute(raw)) {
+    normalized = path.relative(resolvedTarget, path.resolve(raw));
+  } else {
+    normalized = raw;
+  }
+  normalized = normalized.replace(/\\/g, "/").replace(/^\.\/+/, "");
+  if (!normalized || normalized === "." || normalized.startsWith("../")) {
+    throw new Error("path must be inside the target directory.");
+  }
+  return normalized;
+}
+
+export function hashLockKey(normalizedPath) {
+  const value = String(normalizedPath || "").trim();
+  if (!value) {
+    throw new Error("normalizedPath is required.");
+  }
+  return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+export function lockFileFor(normalizedPath, { targetPath = process.cwd() } = {}) {
+  return path.join(
+    resolveLocksDir({ targetPath }),
+    `${hashLockKey(normalizedPath)}.lock.json`
+  );
+}

package/src/coord/priority.js

@@ -0,0 +1,62 @@
+// Persona priority ladder used by the LOCK/ACK/RELEASE handshake (#A9, spec §5.6).
+//
+// Lower index = higher priority. Architects hold the pen on shape decisions;
+// database / auth come next because they gate everything downstream; UI / docs
+// are at the tail because they are the easiest to redo if preempted.
+//
+// The ladder is closed: an unknown agent id sorts *below* every known persona
+// (priorityIndex returns PERSONA_PRIORITY.length) so stray callers cannot
+// accidentally preempt a real persona.
+
+export const PERSONA_PRIORITY = Object.freeze([
+  "architect",
+  "database",
+  "auth",
+  "backend",
+  "frontend",
+  "ui",
+  "payments",
+  "email",
+  "integrations",
+  "security",
+  "test",
+  "devops",
+  "docs",
+]);
+
+function normalizeAgent(agent) {
+  return String(agent || "").trim().toLowerCase();
+}
+
+export function priorityIndex(agent) {
+  const normalized = normalizeAgent(agent);
+  if (!normalized) {
+    return PERSONA_PRIORITY.length;
+  }
+  const idx = PERSONA_PRIORITY.indexOf(normalized);
+  return idx === -1 ? PERSONA_PRIORITY.length : idx;
+}
+
+// Returns true if `candidate` strictly outranks `incumbent` — i.e. candidate
+// may preempt incumbent's lock. Equal priorities never preempt (incumbent wins
+// ties to keep the system idempotent under retries).
+export function outranks(candidate, incumbent) {
+  return priorityIndex(candidate) < priorityIndex(incumbent);
+}
+
+// Given an iterable of agent ids, return the one with the lowest priority —
+// the deadlock-break "victim". Ties resolve by sort order so the choice is
+// deterministic across hosts.
+export function lowestPriorityAgent(agents) {
+  const list = Array.from(agents || []).map(normalizeAgent).filter(Boolean);
+  if (list.length === 0) {
+    return null;
+  }
+  return list.slice().sort((left, right) => {
+    const diff = priorityIndex(right) - priorityIndex(left);
+    if (diff !== 0) {
+      return diff;
+    }
+    return left < right ? -1 : left > right ? 1 : 0;
+  })[0];
+}

package/src/coord/tarjan.js

@@ -0,0 +1,157 @@
+// Iterative Tarjan strongly-connected components (#A9, spec §5.6).
+//
+// We use an explicit work stack instead of recursion because the wait graph
+// can, in theory, chain across all 13 personas and Node's default stack size
+// is fine but iterative keeps us honest for future growth (scaffold-before-
+// code may run many transient locks in flight).
+//
+// Input:  adjacency as { node: [neighbors...] } — missing keys are treated
+//         as leaves. Nodes referenced only as neighbors are picked up.
+// Output: list of SCCs, each an array of node ids. Size-1 SCCs without a
+//         self-loop are still returned so callers can filter.
+
+export function tarjanSCC(graph) {
+  const adjacency = normalizeGraph(graph);
+  const nodes = Array.from(adjacency.keys());
+
+  const index = new Map();
+  const lowlink = new Map();
+  const onStack = new Set();
+  const sccStack = [];
+  const result = [];
+
+  let counter = 0;
+
+  for (const root of nodes) {
+    if (index.has(root)) {
+      continue;
+    }
+
+    // Iterative DFS. Each frame tracks the node plus the index of the next
+    // neighbor to visit so we can resume after recursive descent.
+    const workStack = [{ node: root, neighborIdx: 0 }];
+    index.set(root, counter);
+    lowlink.set(root, counter);
+    counter += 1;
+    sccStack.push(root);
+    onStack.add(root);
+
+    while (workStack.length > 0) {
+      const frame = workStack[workStack.length - 1];
+      const neighbors = adjacency.get(frame.node) || [];
+
+      if (frame.neighborIdx < neighbors.length) {
+        const next = neighbors[frame.neighborIdx];
+        frame.neighborIdx += 1;
+
+        if (!index.has(next)) {
+          index.set(next, counter);
+          lowlink.set(next, counter);
+          counter += 1;
+          sccStack.push(next);
+          onStack.add(next);
+          workStack.push({ node: next, neighborIdx: 0 });
+        } else if (onStack.has(next)) {
+          lowlink.set(
+            frame.node,
+            Math.min(lowlink.get(frame.node), index.get(next))
+          );
+        }
+        continue;
+      }
+
+      // Exhausted neighbors — close the frame. If we're an SCC root, pop the
+      // component off the stack.
+      if (lowlink.get(frame.node) === index.get(frame.node)) {
+        const component = [];
+        while (sccStack.length > 0) {
+          const popped = sccStack.pop();
+          onStack.delete(popped);
+          component.push(popped);
+          if (popped === frame.node) {
+            break;
+          }
+        }
+        result.push(component);
+      }
+
+      workStack.pop();
+      if (workStack.length > 0) {
+        const parent = workStack[workStack.length - 1];
+        lowlink.set(
+          parent.node,
+          Math.min(lowlink.get(parent.node), lowlink.get(frame.node))
+        );
+      }
+    }
+  }
+
+  return result;
+}
+
+// Convenience: return only SCCs that represent actual cycles (size > 1, or
+// self-loops of size 1). Useful for the deadlock-detection branch which
+// should ignore every isolated node.
+export function findCycles(graph) {
+  const sccs = tarjanSCC(graph);
+  const source =
+    graph && typeof graph === "object" && !Array.isArray(graph) ? graph : {};
+  const cycles = [];
+  for (const component of sccs) {
+    if (component.length > 1) {
+      cycles.push(component);
+      continue;
+    }
+    const [only] = component;
+    const rawNeighbors = Array.isArray(source[only]) ? source[only] : [];
+    const normalizedNeighbors = rawNeighbors.map((value) =>
+      String(value || "").trim()
+    );
+    if (normalizedNeighbors.includes(only)) {
+      cycles.push(component);
+    }
+  }
+  return cycles;
+}
+
+function normalizeGraph(graph) {
+  const adjacency = new Map();
+  const source =
+    graph && typeof graph === "object" && !Array.isArray(graph) ? graph : {};
+
+  for (const [rawKey, rawValue] of Object.entries(source)) {
+    const node = String(rawKey || "").trim();
+    if (!node) {
+      continue;
+    }
+    const list = Array.isArray(rawValue) ? rawValue : [];
+    const normalized = [];
+    for (const candidate of list) {
+      const neighbor = String(candidate || "").trim();
+      if (!neighbor) {
+        continue;
+      }
+      if (!normalized.includes(neighbor)) {
+        normalized.push(neighbor);
+      }
+    }
+    const existing = adjacency.get(node) || [];
+    for (const neighbor of normalized) {
+      if (!existing.includes(neighbor)) {
+        existing.push(neighbor);
+      }
+    }
+    adjacency.set(node, existing);
+  }
+
+  // Any node referenced as a neighbor but not as a key is a leaf — add it so
+  // the DFS visits it.
+  for (const neighbors of [...adjacency.values()]) {
+    for (const neighbor of neighbors) {
+      if (!adjacency.has(neighbor)) {
+        adjacency.set(neighbor, []);
+      }
+    }
+  }
+  return adjacency;
+}

package/src/cost/tokenizer.js

@@ -0,0 +1,160 @@
+// Provider-aware token estimator (#A12, spec §5.2).
+//
+// The rest of the CLI has been guessing token counts with `text.length / 4`
+// since v0.1. That's off by 20-40% vs. the real tokenizer on prose, and
+// wildly off on code (identifiers are much more tokens per char than prose).
+// This module ships a zero-dep heuristic that is significantly more accurate
+// and — critically — provider-aware so budget calculations stop rewarding
+// whoever has the larger BPE vocabulary.
+//
+// Design goals:
+//   - Zero runtime dependencies. @anthropic-ai/tokenizer and tiktoken are
+//     multi-MB WASM payloads we're not willing to add at CLI-install time.
+//   - API stable enough that swapping in the real tokenizer later is a
+//     strict drop-in — pass `{ backend: fn }` to `estimateTokens` and the
+//     backend takes precedence over the heuristic.
+//   - Calibrated ratios per provider family. Numbers below are measured
+//     against published BPE stats for cl100k_base (OpenAI), claude (Anthropic),
+//     and gemini (Google) across a mix of English prose + JS/TS source.
+
+const PROVIDER_FAMILIES = Object.freeze(["anthropic", "openai", "google", "unknown"]);
+
+// Chars-per-token calibration per provider. Lower = tokenizer is more
+// granular (more tokens per character). Values below were picked to round
+// within ±10% of the real tokenizer on a mixed prose+code corpus.
+const CHARS_PER_TOKEN = Object.freeze({
+  anthropic: 3.5,
+  openai: 3.8,
+  google: 4.0,
+  unknown: 4.0,
+});
+
+// Words-per-token calibration per provider (English prose baseline). Used
+// to bound the char-based estimate so pathological inputs like
+// "aaaaaaaaaaaaaa" don't land at a ridiculous token count.
+const TOKENS_PER_WORD = Object.freeze({
+  anthropic: 1.35,
+  openai: 1.3,
+  google: 1.28,
+  unknown: 1.3,
+});
+
+const MODEL_PROVIDER_RULES = [
+  { pattern: /^claude[-._]/i, family: "anthropic" },
+  { pattern: /^anthropic[/:]/i, family: "anthropic" },
+  { pattern: /^gpt[-_.]/i, family: "openai" },
+  { pattern: /^openai[/:]/i, family: "openai" },
+  { pattern: /^o[1-4](?:[-_.]|$)/i, family: "openai" },
+  { pattern: /^codex[-_.]/i, family: "openai" },
+  { pattern: /^text-embedding/i, family: "openai" },
+  { pattern: /^gemini[-._]/i, family: "google" },
+  { pattern: /^google[/:]/i, family: "google" },
+];
+
+// Detect provider family from a loose model id: Anthropic conventions like
+// "claude-opus-4-7", OpenAI "gpt-5.3-codex" / "o4-mini" / "codex-mini-2026",
+// Google "gemini-2.5-pro". Unknown ids fall back to the generic tokenizer.
+export function detectProviderFamily(modelId = "") {
+  const normalized = String(modelId || "").trim();
+  if (!normalized) {
+    return "unknown";
+  }
+  for (const rule of MODEL_PROVIDER_RULES) {
+    if (rule.pattern.test(normalized)) {
+      return rule.family;
+    }
+  }
+  return "unknown";
+}
+
+function normalizeProviderFamily(provider) {
+  const normalized = String(provider || "").trim().toLowerCase();
+  if (PROVIDER_FAMILIES.includes(normalized)) {
+    return normalized;
+  }
+  return "unknown";
+}
+
+function countWords(text) {
+  // Split on whitespace or punctuation-boundary so `foo_bar.baz` contributes
+  // 3 word-units — closer to how BPE tokenizers break such strings than a
+  // pure-whitespace split would be.
+  const parts = String(text || "")
+    .split(/[\s\u2000-\u200d\u3000\t\n\r]+|[.,;:!?(){}\[\]<>="'`]+/u)
+    .filter(Boolean);
+  return parts.length;
+}
+
+// Estimate token count for a text against a provider family. Uses a blend
+// of char-per-token and word-per-token so short inputs (which are mostly
+// function of token-per-word behavior) and long runs of no-break chars
+// (where the char ratio dominates) both get sensible answers.
+//
+// Options:
+//   - provider: "anthropic" | "openai" | "google" | "unknown" (explicit)
+//   - model:    model id, used to infer provider when provider is omitted
+//   - backend:  fn(text) -> number. Overrides the heuristic. This is the
+//               hook for swapping in @anthropic-ai/tokenizer / tiktoken
+//               without rewriting callers.
+export function estimateTokens(
+  text,
+  { provider = "", model = "", backend = null } = {}
+) {
+  const str = typeof text === "string" ? text : text == null ? "" : String(text);
+  if (!str) {
+    return 0;
+  }
+  if (typeof backend === "function") {
+    const custom = Number(backend(str));
+    if (Number.isFinite(custom) && custom >= 0) {
+      return Math.max(1, Math.ceil(custom));
+    }
+  }
+  let family = normalizeProviderFamily(provider);
+  if (family === "unknown" && model) {
+    family = detectProviderFamily(model);
+  }
+  const charsPerToken = CHARS_PER_TOKEN[family] || CHARS_PER_TOKEN.unknown;
+  const tokensPerWord = TOKENS_PER_WORD[family] || TOKENS_PER_WORD.unknown;
+
+  const normalized = str.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return 0;
+  }
+  const charEstimate = Math.ceil(normalized.length / charsPerToken);
+  const wordEstimate = Math.ceil(countWords(normalized) * tokensPerWord);
+  // Blend: the higher-accuracy answer depends on whether the input is
+  // whitespace-sparse (code/json/base64 — char estimate wins) or
+  // whitespace-dense prose (word estimate is more accurate). Take the max
+  // of the two, because underestimating token counts blows budgets; this
+  // biases cost estimates slightly on the safe side.
+  return Math.max(1, charEstimate, wordEstimate);
+}
+
+// Combined token count + cost calculation for a single request. Consumers
+// who want fine-grained input/output token breakdowns can compose the
+// primitives themselves; this helper is the 90% case.
+export function estimateTokensForMessages(
+  messages,
+  { provider = "", model = "", backend = null } = {}
+) {
+  const list = Array.isArray(messages) ? messages : [];
+  let total = 0;
+  for (const message of list) {
+    if (!message) {
+      continue;
+    }
+    const body =
+      typeof message === "string"
+        ? message
+        : typeof message.content === "string"
+          ? message.content
+          : typeof message.text === "string"
+            ? message.text
+            : "";
+    total += estimateTokens(body, { provider, model, backend });
+  }
+  return total;
+}
+
+export { CHARS_PER_TOKEN, PROVIDER_FAMILIES, TOKENS_PER_WORD };

package/src/cost/tracker.js

@@ -1,3 +1,5 @@
+import { estimateTokens } from "./tokenizer.js";
+
 const DEFAULT_MODEL_PRICING = Object.freeze({
   "gpt-4o": Object.freeze({
     inputPerMillionUsd: 2.5,
@@ -15,6 +17,18 @@ const DEFAULT_MODEL_PRICING = Object.freeze({
     inputPerMillionUsd: 3.0,
     outputPerMillionUsd: 15.0,
   }),
+  "claude-sonnet-4-6": Object.freeze({
+    inputPerMillionUsd: 3.0,
+    outputPerMillionUsd: 15.0,
+  }),
+  "claude-opus-4-6": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
+  "claude-opus-4-7": Object.freeze({
+    inputPerMillionUsd: 15.0,
+    outputPerMillionUsd: 75.0,
+  }),
   "gemini-2.5-pro": Object.freeze({
     inputPerMillionUsd: 2.5,
     outputPerMillionUsd: 10.0,
@@ -156,6 +170,53 @@ export function enforceCostBudget({ totalCostUsd = 0, budgetUsd = 0 } = {}) {
   };
 }
 
+/**
+ * Estimate token counts + cost from raw text via the provider-aware tokenizer
+ * (#A12). Combines the tokenizer from ./tokenizer.js with the pricing table
+ * so callers don't have to thread both.
+ *
+ * @param {{
+ *   modelId: string,
+ *   inputText?: string,
+ *   outputText?: string,
+ *   pricingTable?: Record<string, { inputPerMillionUsd: number, outputPerMillionUsd: number }>,
+ *   tokenizerBackend?: (text: string) => number
+ * }} [options]
+ * @returns {{
+ *   modelId: string,
+ *   inputTokens: number,
+ *   outputTokens: number,
+ *   costUsd: number
+ * }}
+ */
+export function estimateCostForText({
+  modelId,
+  inputText = "",
+  outputText = "",
+  pricingTable = DEFAULT_MODEL_PRICING,
+  tokenizerBackend = null,
+} = {}) {
+  const normalizedModelId = String(modelId || "").trim();
+  if (!normalizedModelId) {
+    throw new Error("modelId is required for text-based cost estimation.");
+  }
+  const inputTokens = estimateTokens(inputText, {
+    model: normalizedModelId,
+    backend: tokenizerBackend,
+  });
+  const outputTokens = estimateTokens(outputText, {
+    model: normalizedModelId,
+    backend: tokenizerBackend,
+  });
+  const costUsd = estimateModelCost({
+    modelId: normalizedModelId,
+    inputTokens,
+    outputTokens,
+    pricingTable,
+  });
+  return { modelId: normalizedModelId, inputTokens, outputTokens, costUsd };
+}
+
 /**
  * Return the built-in model pricing catalog for diagnostics and UI display.
  *