sentinelayer-cli 0.8.8 → 0.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/session/agent-registry.js

@@ -7,6 +7,11 @@ import { STUCK_THRESHOLDS } from "../agents/jules/pulse.js";
 import { createAgentEvent } from "../events/schema.js";
 import { resolveSessionPaths } from "./paths.js";
 import { emitContextBriefing } from "./recap.js";
+import {
+  assignFriendlyName,
+  buildSentiWelcome,
+  shouldAutoRenameInRegistry,
+} from "./senti-naming.js";
 import { appendToStream } from "./stream.js";
 
 const AGENT_SNAPSHOT_SCHEMA_VERSION = "1.0.0";
@@ -181,7 +186,26 @@ export async function registerAgent(
 ) {
   const paths = resolveSessionPaths(sessionId, { targetPath });
   const nowIso = new Date().toISOString();
-  const resolvedAgentId = normalizeString(agentId) || generateAgentId(model);
+  const originalCallerAgentId = normalizeString(agentId);
+  let resolvedAgentId = originalCallerAgentId || generateAgentId(model);
+  let renamedFrom = "";
+
+  // Senti orchestrator hook: when the caller didn't supply an id, or
+  // supplied an explicit placeholder (`cli-user`, `agent-…`, `guest-…`),
+  // pick a friendly sequential name like `claude-3` / `codex-2` /
+  // `guest-1` so participants have a "face" in the transcript instead of
+  // a random hex blob. Caller-supplied real ids are NEVER renamed
+  // (kill tests like PR 348/351 register `codex-task-holder-1` with
+  // model="" and need the id to round-trip verbatim).
+  if (shouldAutoRenameInRegistry({ originalCallerAgentId })) {
+    const existingAgents = await listAgentsInternal(paths);
+    const friendly = assignFriendlyName({ model, existingAgents });
+    if (friendly && friendly !== resolvedAgentId.toLowerCase()) {
+      renamedFrom = resolvedAgentId;
+      resolvedAgentId = friendly;
+    }
+  }
+
   const snapshotPath = buildAgentSnapshotPath(paths, resolvedAgentId);
 
   const snapshot = normalizeAgentSnapshot(
@@ -210,6 +234,21 @@ export async function registerAgent(
     role: snapshot.role,
     status: snapshot.status,
   }, { targetPath });
+
+  if (renamedFrom) {
+    const welcome = buildSentiWelcome({
+      agentId: snapshot.agentId,
+      model: snapshot.model,
+      role: snapshot.role,
+      wasAnonymous: true,
+      originalAgentId: renamedFrom,
+    });
+    await emitAgentEvent(paths.sessionId, "agent_identified", {
+      ...welcome,
+      sessionId: paths.sessionId,
+    }, { targetPath });
+  }
+
   if (normalizeString(snapshot.agentId).toLowerCase() !== "senti") {
     await emitContextBriefing(paths.sessionId, {
       forAgentId: snapshot.agentId,
@@ -223,6 +262,26 @@ export async function registerAgent(
   };
 }
 
+async function listAgentsInternal(paths) {
+  try {
+    const entries = await fsp.readdir(paths.agentsDir, { withFileTypes: true });
+    const out = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const raw = await readAgentSnapshot(path.join(paths.agentsDir, entry.name));
+      if (raw && typeof raw === "object" && raw.agentId) {
+        out.push({ agentId: raw.agentId, model: raw.model || "" });
+      }
+    }
+    return out;
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
 export async function heartbeatAgent(
   sessionId,
   agentId,

package/src/session/senti-naming.js

@@ -0,0 +1,180 @@
+/**
+ * Senti — auto-name + welcome anonymous participants.
+ *
+ * When an agent joins without a clear name + model, Senti steps in:
+ *
+ *  1. `assignFriendlyName({ model, existingAgents })` — generates a
+ *     stable, human-readable id like "guest-3", "claude-2",
+ *     "codex-anon-1" derived from the model family + the next free
+ *     ordinal in the session. Sequential beats hex-suffix for the
+ *     ChatGPT-style "everyone has a face" UX Carter asked for.
+ *
+ *  2. `buildSentiWelcome({ agentId, model, role })` — produces the
+ *     payload for an `agent_identified` event Senti emits in the
+ *     stream so the new participant + everyone watching sees the
+ *     auto-assignment + how to override it.
+ *
+ *  3. `isAnonymousAgent({ agentId, model })` — single-source check
+ *     for "this registration didn't carry real identity" used by
+ *     callers to decide whether to invoke (1) and (2). Generic
+ *     prefixes (`agent-…`, `cli-user`) and unknown models qualify.
+ *
+ * This module never touches the network or the disk; it's pure naming
+ * logic that the agent-registry wires into the registration path.
+ */
+
+const ANONYMOUS_AGENT_PREFIXES = Object.freeze(["agent-", "cli-user", "guest-"]);
+const ANONYMOUS_MODELS = Object.freeze(["", "unknown", "cli", "anonymous"]);
+
+/**
+ * Strict: should the agent-registry auto-rename this registration?
+ *
+ * The hook's contract is "if a name is already there, leave it alone; if
+ * not, give them one." So we ONLY auto-rename when the caller gave us
+ * nothing OR the literal default placeholder `cli-user`. Any other
+ * caller-supplied id — even ones that *look* generic like `agent-alpha`,
+ * `guest-team`, or `codex-task-holder-1` — was an intentional choice and
+ * round-trips verbatim.
+ *
+ * Why so strict:
+ *  - e2e test #91 (CLI session commands flow) does `session join
+ *    --name agent-alpha` and asserts the id round-trips. The previous
+ *    rule (`agent-` prefix => rename) clobbered it.
+ *  - PR 348/351 kill tests register `codex-task-holder-1` with model=""
+ *    and need verbatim round-trip.
+ *  - `isAnonymousAgent` is intentionally separate and stays permissive
+ *    (model can flag) for downstream callers that decide whether to
+ *    *welcome* a participant; the registry hook is stricter.
+ *
+ * @param {{originalCallerAgentId: string}} params
+ * @returns {boolean}
+ */
+export function shouldAutoRenameInRegistry({ originalCallerAgentId = "" } = {}) {
+  const id = normalize(originalCallerAgentId).toLowerCase();
+  if (!id) return true;
+  return id === "cli-user";
+}
+
+/**
+ * @typedef {object} AgentLike
+ * @property {string} agentId
+ * @property {string} [model]
+ */
+
+function normalize(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function familyFromModel(modelName) {
+  const lower = normalize(modelName).toLowerCase();
+  if (!lower || lower === "unknown" || lower === "anonymous") return "guest";
+  if (lower.includes("claude") || lower.includes("sonnet") || lower.includes("opus")) {
+    return "claude";
+  }
+  if (lower.includes("codex") || lower.includes("gpt-")) return "codex";
+  if (lower.includes("gemini")) return "gemini";
+  if (lower.includes("senti") || lower.includes("sentinel")) return "senti";
+  if (lower === "cli") return "guest";
+  // Otherwise use the first sanitized token so distinct providers stay
+  // distinct even when we don't recognize them.
+  const token = lower.split(/[\s:/_-]+/).find(Boolean) || "guest";
+  return token.replace(/[^a-z0-9]/g, "") || "guest";
+}
+
+/**
+ * Given the existing agent roster + the model the new participant
+ * declared (which may be empty/unknown), pick the next free ordinal
+ * within that family and return `<family>-<ordinal>`. Stable across
+ * runs because we pass the existing agents in.
+ *
+ * @param {{model?: string, existingAgents?: Array<AgentLike>}} params
+ * @returns {string}
+ */
+export function assignFriendlyName({ model = "", existingAgents = [] } = {}) {
+  const family = familyFromModel(model);
+  const taken = new Set(
+    (Array.isArray(existingAgents) ? existingAgents : [])
+      .map((agent) => normalize(agent && agent.agentId).toLowerCase())
+      .filter(Boolean),
+  );
+  for (let n = 1; n <= 9999; n += 1) {
+    const candidate = `${family}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  // Pathological fallback — should never hit in practice, but a
+  // 4-digit ceiling without an escape would be a footgun.
+  return `${family}-${Date.now().toString(36)}`;
+}
+
+/**
+ * Decide whether the registration looks anonymous and therefore needs
+ * Senti to step in with a friendly name. We treat any of:
+ *
+ *  - empty / fallback agentId (`agent-…`, `cli-user`, `guest-…`)
+ *  - empty / unknown / cli model
+ *
+ * as a signal. Either alone is enough — the cli-user default agent
+ * still wants Senti's welcome the first time.
+ *
+ * @param {AgentLike} agent
+ * @returns {boolean}
+ */
+export function isAnonymousAgent(agent = {}) {
+  const id = normalize(agent.agentId).toLowerCase();
+  const model = normalize(agent.model).toLowerCase();
+  const idAnonymous =
+    !id ||
+    ANONYMOUS_AGENT_PREFIXES.some((prefix) => id.startsWith(prefix));
+  const modelAnonymous = ANONYMOUS_MODELS.includes(model);
+  return idAnonymous || modelAnonymous;
+}
+
+/**
+ * Build the payload Senti emits as `agent_identified` when it has
+ * stepped in to name a participant. Consumers (CLI / web) render it
+ * verbatim; the `instructions` line tells the user how to override.
+ *
+ * @param {{
+ *   agentId: string,
+ *   model?: string,
+ *   role?: string,
+ *   sessionId?: string,
+ *   wasAnonymous: boolean,
+ *   originalAgentId?: string,
+ * }} params
+ * @returns {{
+ *   alert: "agent_identified",
+ *   agentId: string,
+ *   model: string,
+ *   role: string,
+ *   wasAnonymous: boolean,
+ *   originalAgentId: string,
+ *   message: string,
+ *   instructions: string,
+ * }}
+ */
+export function buildSentiWelcome({
+  agentId,
+  model = "unknown",
+  role = "observer",
+  wasAnonymous = false,
+  originalAgentId = "",
+} = {}) {
+  const cleanModel = normalize(model) || "unknown";
+  const cleanRole = normalize(role) || "observer";
+  const cleanId = normalize(agentId);
+  const message = wasAnonymous
+    ? `Welcome ${cleanId}. I auto-named you because you joined without a name; introduce yourself anytime.`
+    : `Welcome ${cleanId}. You're in as ${cleanRole}.`;
+  const instructions = `Update with: sl session rename <sessionId> ${cleanId} --to <new-id> [--model <model>]`;
+  return {
+    alert: "agent_identified",
+    agentId: cleanId,
+    model: cleanModel,
+    role: cleanRole,
+    wasAnonymous: Boolean(wasAnonymous),
+    originalAgentId: normalize(originalAgentId),
+    message,
+    instructions,
+  };
+}

package/src/session/transcript.js

@@ -41,6 +41,7 @@ const TRANSCRIPT_EVENT_KINDS = new Set([
   "session_message",
   "session_say",
   "agent_response",
+  "session_usage",
   "human_relay",
   "agent_join",
   "agent_left",
@@ -153,9 +154,14 @@ function eventTimestamp(event) {
 
 function eventBody(event) {
   const payload = event && typeof event.payload === "object" ? event.payload : {};
+  // session_usage carries the response inside payload.response.text
+  const responseText =
+    typeof payload.response === "object" && payload.response
+      ? payload.response.text
+      : payload.response;
   const text =
     payload.message ||
-    payload.response ||
+    responseText ||
     payload.text ||
     payload.alert ||
     payload.reason ||

package/src/session/usage.js

@@ -0,0 +1,213 @@
+/**
+ * Session usage emitter — records every LLM interaction inside a session
+ * as a `session_usage` event so consumers (web dashboard, transcript
+ * download, telemetry sync) can surface live, accurate token + cost
+ * counters per-agent + session-wide.
+ *
+ * Senti orchestrator philosophy: "tokens on point every time any LLM
+ * interacts." Every persona / Jules / Codex / Claude call inside a
+ * session should land here so the running tally is authoritative.
+ *
+ * Event shape:
+ *
+ *   {
+ *     event: "session_usage",
+ *     ts: ISO8601,
+ *     agent: { id, model },
+ *     payload: {
+ *       interactionId,           // stable id for the LLM call
+ *       agentId, model, role,
+ *       inputTokens, outputTokens, totalTokens,
+ *       costUsd,
+ *       durationMs,              // wall-clock duration of the call
+ *       prompt: { tokens, chars },
+ *       response: { tokens, chars, text? },
+ *       usage: {                 // mirrors transcript.js payload.usage
+ *         totalTokens,
+ *         costUsd,
+ *         inputTokens,
+ *         outputTokens,
+ *       },
+ *     }
+ *   }
+ *
+ * Design choice: emit BOTH the convenient flat fields AND a
+ * `payload.usage` block, so transcript.js's existing usage roll-up
+ * picks it up without changes, while web UIs can display the structured
+ * fields directly without re-parsing.
+ */
+
+import process from "node:process";
+import { randomUUID } from "node:crypto";
+
+import { createAgentEvent } from "../events/schema.js";
+import { resolveSessionPaths } from "./paths.js";
+import { appendToStream } from "./stream.js";
+
+const SESSION_USAGE_EVENT = "session_usage";
+
+function n(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function num(value) {
+  const v = Number(value);
+  return Number.isFinite(v) && v >= 0 ? v : 0;
+}
+
+function clipText(text, max = 4000) {
+  const s = n(text);
+  if (s.length <= max) return s;
+  return `${s.slice(0, max)}…`;
+}
+
+/**
+ * Emit a `session_usage` event into the session's NDJSON stream.
+ *
+ * @param {string} sessionId
+ * @param {object} params
+ * @param {string} params.agentId
+ * @param {string} [params.agentModel]
+ * @param {string} [params.role]
+ * @param {number} [params.inputTokens]
+ * @param {number} [params.outputTokens]
+ * @param {number} [params.costUsd]
+ * @param {number} [params.durationMs]
+ * @param {string} [params.prompt]            full prompt text (clipped)
+ * @param {string} [params.response]          full response text (clipped)
+ * @param {string} [params.interactionId]     opaque id for cross-event correlation
+ * @param {string} [params.targetPath]        workspace path (default cwd)
+ * @returns {Promise<{ event: string, interactionId: string, totalTokens: number, costUsd: number }>}
+ */
+export async function emitLLMInteraction(
+  sessionId,
+  {
+    agentId,
+    agentModel = "",
+    role = "",
+    inputTokens = 0,
+    outputTokens = 0,
+    costUsd = 0,
+    durationMs = 0,
+    prompt = "",
+    response = "",
+    interactionId = "",
+    targetPath = process.cwd(),
+  } = {},
+) {
+  const sid = n(sessionId);
+  if (!sid) throw new Error("sessionId is required.");
+  const aid = n(agentId);
+  if (!aid) throw new Error("agentId is required.");
+
+  const paths = resolveSessionPaths(sid, { targetPath });
+  const ts = new Date().toISOString();
+  const id = n(interactionId) || randomUUID();
+  const inT = Math.floor(num(inputTokens));
+  const outT = Math.floor(num(outputTokens));
+  const totalT = inT + outT;
+  const cost = Math.round(num(costUsd) * 1_000_000) / 1_000_000;
+
+  const promptText = clipText(prompt);
+  const responseText = clipText(response);
+
+  const payload = {
+    interactionId: id,
+    agentId: aid,
+    model: n(agentModel) || "unknown",
+    role: n(role) || "observer",
+    inputTokens: inT,
+    outputTokens: outT,
+    totalTokens: totalT,
+    costUsd: cost,
+    durationMs: Math.max(0, Math.floor(num(durationMs))),
+    prompt: { tokens: inT, chars: promptText.length },
+    response: {
+      tokens: outT,
+      chars: responseText.length,
+      text: responseText || undefined,
+    },
+    // Mirror into payload.usage so transcript.js + telemetry sync pick
+    // it up via the same code path used for ad-hoc agent_response usage.
+    usage: {
+      totalTokens: totalT,
+      costUsd: cost,
+      inputTokens: inT,
+      outputTokens: outT,
+    },
+  };
+
+  const envelope = createAgentEvent({
+    event: SESSION_USAGE_EVENT,
+    agentId: aid,
+    agentModel: n(agentModel) || "unknown",
+    sessionId: paths.sessionId,
+    payload,
+    ts,
+  });
+
+  await appendToStream(paths.sessionId, envelope, { targetPath });
+  return {
+    event: SESSION_USAGE_EVENT,
+    interactionId: id,
+    totalTokens: totalT,
+    costUsd: cost,
+  };
+}
+
+/**
+ * Aggregate `session_usage` events into a per-agent + global tally.
+ * Pure helper for renderers that want a snapshot at a point in time.
+ *
+ * @param {Array<object>} events
+ * @returns {{
+ *   perAgent: Map<string, { agentId, model, totalTokens, inputTokens, outputTokens, costUsd, interactions }>,
+ *   totals: { totalTokens, inputTokens, outputTokens, costUsd, interactions },
+ * }}
+ */
+export function aggregateSessionUsage(events = []) {
+  const perAgent = new Map();
+  const totals = {
+    totalTokens: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    costUsd: 0,
+    interactions: 0,
+  };
+  for (const event of events) {
+    if (!event || event.event !== SESSION_USAGE_EVENT) continue;
+    const payload = event.payload || {};
+    const agentId = n(payload.agentId || event.agent?.id);
+    if (!agentId) continue;
+    if (!perAgent.has(agentId)) {
+      perAgent.set(agentId, {
+        agentId,
+        model: n(payload.model || event.agent?.model) || "unknown",
+        totalTokens: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        costUsd: 0,
+        interactions: 0,
+      });
+    }
+    const record = perAgent.get(agentId);
+    record.totalTokens += num(payload.totalTokens);
+    record.inputTokens += num(payload.inputTokens);
+    record.outputTokens += num(payload.outputTokens);
+    record.costUsd += num(payload.costUsd);
+    record.interactions += 1;
+
+    totals.totalTokens += num(payload.totalTokens);
+    totals.inputTokens += num(payload.inputTokens);
+    totals.outputTokens += num(payload.outputTokens);
+    totals.costUsd += num(payload.costUsd);
+    totals.interactions += 1;
+  }
+  totals.costUsd = Math.round(totals.costUsd * 1_000_000) / 1_000_000;
+  for (const record of perAgent.values()) {
+    record.costUsd = Math.round(record.costUsd * 1_000_000) / 1_000_000;
+  }
+  return { perAgent, totals };
+}
+
+export const SESSION_USAGE_EVENT_KIND = SESSION_USAGE_EVENT;