sentinelayer-cli 0.8.7 → 0.8.9

package/package.json

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

package/src/commands/session.js

@@ -50,7 +50,11 @@ import {
 } from "../session/store.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
 import { readSessionPreview } from "../session/preview.js";
-import { syncSessionMetadataToApi } from "../session/sync.js";
+import {
+  listSessionsFromApi,
+  probeSessionAccess,
+  syncSessionMetadataToApi,
+} from "../session/sync.js";
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import {
@@ -604,6 +608,16 @@ export function registerSessionCommand(program) {
         since: sinceArg,
       });
 
+      // Discriminate "owned-but-no-human-messages" from "not a member /
+      // wrong session id". The hydrate path returns ok:true with
+      // relayed=0 + cursor=null in both cases, which Carter just hit
+      // on session d34f03ba — the user couldn't tell whether they
+      // typed the wrong id or it was just genuinely empty.
+      let access = null;
+      if (result.ok && result.relayed === 0 && !result.cursor) {
+        access = await probeSessionAccess(normalizedSessionId, { targetPath });
+      }
+
       const payload = {
         command: "session sync",
         targetPath,
@@ -614,6 +628,7 @@ export function registerSessionCommand(program) {
         dropped: result.dropped,
         cursor: result.cursor,
         persistedCursor: result.persistedCursor,
+        access: access || undefined,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -623,6 +638,27 @@ export function registerSessionCommand(program) {
         console.log(
           `Hydrated session ${normalizedSessionId}: relayed=${result.relayed} dropped=${result.dropped}.`,
         );
+        if (access && !access.accessible) {
+          if (access.reason === "session_not_found") {
+            console.log(
+              pc.yellow(
+                `Heads up: that session id isn't in your account. Verify with \`sl session list --remote\`.`,
+              ),
+            );
+          } else if (access.reason === "not_a_member") {
+            console.log(
+              pc.yellow(
+                `Heads up: you aren't a member of session ${normalizedSessionId} — sync silently no-ops. Ask the owner to add you, or list your own with \`sl session list --remote\`.`,
+              ),
+            );
+          } else if (access.reason !== "" && access.reason !== "no_session") {
+            console.log(
+              pc.gray(
+                `(probe: ${access.reason}; if you expected messages, check \`sl session list --remote\`.)`,
+              ),
+            );
+          }
+        }
       } else {
         console.log(
           pc.yellow(
@@ -802,6 +838,122 @@ export function registerSessionCommand(program) {
       }
     });
 
+  session
+    .command("download <sessionId>")
+    .description(
+      "Download an iMessage-style Markdown transcript: deterministic timestamps, per-agent active duration, known persona/orchestrator/family avatars, and human avatars from your auth profile",
+    )
+    .option("--out <file>", "Output path (default: <sessionId>.md in cwd)")
+    .option(
+      "--no-system-events",
+      "Suppress join/leave/identified/daemon-alert lines (keeps only user + agent messages)",
+    )
+    .option(
+      "--remote",
+      "Hydrate from the SentinelLayer API before rendering (pulls web-posted messages into the local NDJSON)",
+    )
+    .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 emitJson = shouldEmitJson(options, command);
+
+      let hydration = null;
+      if (options.remote) {
+        hydration = await hydrateSessionFromRemote({
+          sessionId: normalizedSessionId,
+          targetPath,
+        }).catch((error) => ({ ok: false, reason: error?.message || "hydrate_failed" }));
+      }
+
+      const sessionPayload = await getSession(normalizedSessionId, { targetPath });
+      if (!sessionPayload) {
+        throw new Error(`Session '${normalizedSessionId}' was not found.`);
+      }
+
+      const [agents, events] = await Promise.all([
+        listAgents(normalizedSessionId, { targetPath, includeInactive: true }),
+        readStream(normalizedSessionId, { targetPath, tail: 0 }),
+      ]);
+
+      // Pull GitHub/Google avatar + display name from the active auth
+      // session so any human-id seen in the stream renders with the
+      // user's real photo instead of the generic 🧑 fallback.
+      const speakerProfiles = new Map();
+      const auth = await resolveActiveAuthSession({
+        cwd: targetPath,
+        env: process.env,
+        autoRotate: false,
+      }).catch(() => null);
+      const userAvatarUrl = normalizeString(auth?.user?.avatarUrl);
+      const userDisplay =
+        normalizeString(auth?.user?.githubUsername) ||
+        normalizeString(auth?.user?.email);
+      if (userAvatarUrl || userDisplay) {
+        const profile = {
+          displayName: userDisplay || "You",
+          avatarUrl: userAvatarUrl || null,
+          family: "human",
+        };
+        for (const id of ["cli-user", "human", "you", "user"]) {
+          speakerProfiles.set(id, profile);
+        }
+        if (userDisplay) speakerProfiles.set(userDisplay, profile);
+      }
+
+      const { buildTranscriptMarkdown } = await import(
+        "../session/transcript.js"
+      );
+      const { markdown, stats } = buildTranscriptMarkdown({
+        sessionMeta: {
+          sessionId: normalizedSessionId,
+          createdAt: sessionPayload.createdAt,
+          status: sessionPayload.status,
+        },
+        events,
+        agents,
+        speakerProfiles,
+        options: {
+          // commander maps --no-system-events to systemEvents: false
+          includeSystemEvents: options.systemEvents !== false,
+        },
+      });
+
+      const outArg = normalizeString(options.out);
+      const outPath = outArg
+        ? path.resolve(process.cwd(), outArg)
+        : path.resolve(process.cwd(), `${normalizedSessionId}.md`);
+      await fsp.mkdir(path.dirname(outPath), { recursive: true });
+      await fsp.writeFile(outPath, markdown, "utf-8");
+
+      const payload = {
+        command: "session download",
+        sessionId: normalizedSessionId,
+        outPath,
+        bytes: Buffer.byteLength(markdown, "utf-8"),
+        eventCount: events.length,
+        agentCount: agents.length,
+        sessionLiveSeconds: stats.sessionLiveSeconds,
+        sentiActions: stats.sentiActions,
+        totals: stats.totals,
+        remote: hydration,
+      };
+      if (emitJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      console.log(pc.bold(`Downloaded session ${normalizedSessionId} → ${outPath}`));
+      console.log(
+        pc.gray(
+          `${events.length} events · ${agents.length} agents · live ${stats.sessionLiveSeconds}s · senti=${stats.sentiActions} · tokens=${stats.totals.tokenTotal} · cost=$${stats.totals.costTotalUsd.toFixed(4)}`,
+        ),
+      );
+    });
+
   session
     .command("leave <sessionId>")
     .description("Leave a session")
@@ -838,7 +990,13 @@ export function registerSessionCommand(program) {
 
   session
     .command("list")
-    .description("List sessions in the local workspace cache")
+    .description(
+      "List sessions. Defaults to local cache; pass --remote to query the SentinelLayer API for every session on your account.",
+    )
+    .option(
+      "--remote",
+      "Query the API for sessions on the authenticated account (covers sessions created from any workspace or the web dashboard)",
+    )
     .option(
       "--include-archived",
       "Include archived/expired sessions (past conversations)",
@@ -854,18 +1012,80 @@ export function registerSessionCommand(program) {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
       const includeArchived = Boolean(options.includeArchived);
       const limit = parsePositiveInteger(options.limit, "limit", 50);
+      const emitJson = shouldEmitJson(options, command);
+
+      if (options.remote) {
+        const remote = await listSessionsFromApi({
+          targetPath,
+          includeArchived,
+          limit,
+        });
+        const trimmed = emitJson ? remote.sessions : remote.sessions.slice(0, limit);
+        const payload = {
+          command: "session list",
+          source: "remote",
+          targetPath,
+          includeArchived,
+          ok: remote.ok,
+          reason: remote.reason || "",
+          count: remote.count,
+          sessions: trimmed,
+        };
+        if (emitJson) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+        if (!remote.ok) {
+          console.log(
+            pc.yellow(
+              `Remote list unavailable (${remote.reason}). Try \`sl auth login\` or run without --remote for local cache.`,
+            ),
+          );
+          return;
+        }
+        if (remote.sessions.length === 0) {
+          console.log(
+            pc.yellow(
+              includeArchived
+                ? "No sessions on your account."
+                : "No active sessions on your account. Re-run with --include-archived to see history.",
+            ),
+          );
+          return;
+        }
+        for (const item of trimmed) {
+          const archive = item.archiveStatus ? ` archive=${item.archiveStatus}` : "";
+          const created = item.createdAt || "?";
+          const lastActivity = item.lastActivityAt
+            ? ` last=${item.lastActivityAt}`
+            : "";
+          console.log(
+            `${item.sessionId} status=${item.status}${archive} created=${created}${lastActivity}`,
+          );
+        }
+        if (remote.count > trimmed.length) {
+          console.log(
+            pc.gray(
+              `… ${remote.count - trimmed.length} more (raise --limit or use --json).`,
+            ),
+          );
+        }
+        return;
+      }
+
       const sessions = includeArchived
         ? await listAllSessions({ targetPath })
         : await listActiveSessions({ targetPath });
-      const trimmed = shouldEmitJson(options, command) ? sessions : sessions.slice(0, limit);
+      const trimmed = emitJson ? sessions : sessions.slice(0, limit);
       const payload = {
         command: "session list",
+        source: "local",
         targetPath,
         includeArchived,
         count: sessions.length,
         sessions: trimmed,
       };
-      if (shouldEmitJson(options, command)) {
+      if (emitJson) {
         console.log(JSON.stringify(payload, null, 2));
         return;
       }
@@ -873,8 +1093,8 @@ export function registerSessionCommand(program) {
         console.log(
           pc.yellow(
             includeArchived
-              ? "No sessions in cache."
-              : "No active sessions. Run with --include-archived to see history.",
+              ? "No sessions in local cache. Run with --remote to fetch from the API."
+              : "No active sessions in local cache. Run with --remote to see sessions from other workspaces or the web.",
           ),
         );
         return;

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

@@ -735,6 +735,161 @@ export async function pollHumanMessages(
   }
 }
 
+/**
+ * List sessions owned by the active user via `GET /api/v1/sessions`.
+ *
+ * Mirrors the failure shape of `pollHumanMessages` so callers can render
+ * a single error path: `{ ok, reason, sessions, count }`. Sessions are
+ * returned in API order (newest-first per the server's contract); the
+ * caller is responsible for any further sort or filter.
+ *
+ * @param {object} [options]
+ * @param {string} [options.targetPath]
+ * @param {boolean} [options.includeArchived]
+ * @param {number} [options.limit]
+ * @param {Function} [options.resolveAuthSession]
+ * @param {Function} [options.fetchImpl]
+ * @returns {Promise<{ok: boolean, reason: string, sessions: Array<object>, count: number}>}
+ */
+export async function listSessionsFromApi({
+  targetPath = process.cwd(),
+  includeArchived = false,
+  limit = 50,
+  resolveAuthSession = resolveActiveAuthSession,
+  fetchImpl = fetchWithTimeout,
+  timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+} = {}) {
+  let session;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { ok: false, reason: "no_session", sessions: [], count: 0 };
+  }
+  if (!session || !session.token) {
+    return { ok: false, reason: "not_authenticated", sessions: [], count: 0 };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const query = new URLSearchParams();
+  if (includeArchived) query.set("include_archived", "true");
+  const normalizedLimit = Math.max(1, Math.min(200, normalizePositiveInteger(limit, 50)));
+  query.set("limit", String(normalizedLimit));
+  const endpoint = `${apiBaseUrl}/api/v1/sessions?${query.toString()}`;
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      reason: normalizeString(err?.message) || "list_failed",
+      sessions: [],
+      count: 0,
+    };
+  }
+  if (!response || !response.ok) {
+    return {
+      ok: false,
+      reason: `api_${response ? response.status : "no_response"}`,
+      sessions: [],
+      count: 0,
+    };
+  }
+  const payload = await response.json().catch(() => ({}));
+  const sessions = Array.isArray(payload?.sessions) ? payload.sessions : [];
+  return {
+    ok: true,
+    reason: "",
+    sessions,
+    count: typeof payload?.count === "number" ? payload.count : sessions.length,
+  };
+}
+
+/**
+ * Probe whether a single session is visible to the active user.
+ *
+ * Used by `session sync` to discriminate between "owned but empty" and
+ * "not a member / wrong session id" — the former is a quiet success,
+ * the latter deserves a loud hint.
+ *
+ * @returns {Promise<{accessible: boolean, reason: string, status?: number}>}
+ */
+export async function probeSessionAccess(
+  sessionId,
+  {
+    targetPath = process.cwd(),
+    resolveAuthSession = resolveActiveAuthSession,
+    fetchImpl = fetchWithTimeout,
+    timeoutMs = DEFAULT_SYNC_TIMEOUT_MS,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { accessible: false, reason: "invalid_session_id" };
+  }
+
+  let session;
+  try {
+    session = await resolveAuthSession({
+      cwd: targetPath,
+      env: process.env,
+      autoRotate: false,
+    });
+  } catch {
+    return { accessible: false, reason: "no_session" };
+  }
+  if (!session || !session.token) {
+    return { accessible: false, reason: "not_authenticated" };
+  }
+
+  const apiBaseUrl = resolveApiBaseUrl(session);
+  const endpoint = `${apiBaseUrl}/api/v1/sessions/${encodeURIComponent(
+    normalizedSessionId,
+  )}/events?limit=1`;
+
+  let response;
+  try {
+    response = await fetchImpl(
+      endpoint,
+      {
+        method: "GET",
+        headers: { Authorization: `Bearer ${session.token}` },
+      },
+      normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
+    );
+  } catch (err) {
+    return {
+      accessible: false,
+      reason: normalizeString(err?.message) || "probe_failed",
+    };
+  }
+
+  if (response && response.ok) {
+    return { accessible: true, reason: "", status: response.status };
+  }
+  if (!response) {
+    return { accessible: false, reason: "no_response" };
+  }
+  if (response.status === 403) {
+    return { accessible: false, reason: "not_a_member", status: 403 };
+  }
+  if (response.status === 404) {
+    return { accessible: false, reason: "session_not_found", status: 404 };
+  }
+  return { accessible: false, reason: `api_${response.status}`, status: response.status };
+}
+
 export function resetSessionSyncStateForTests() {
   outboundCircuit.consecutiveFailures = 0;
   outboundCircuit.openedAtMs = 0;

package/src/session/transcript.js

@@ -0,0 +1,429 @@
+/**
+ * Session transcript renderer — produces an iMessage-style Markdown
+ * document from a session's NDJSON event stream + agent roster +
+ * metadata. Deterministic: same inputs → identical output (modulo the
+ * `generatedAt` line in the header).
+ *
+ * Adds at render time:
+ *   - Per-agent active duration (first → last event with that agent id)
+ *   - Total session live-for (createdAt → last event)
+ *   - Token + cost roll-up if events carry usage payloads
+ *   - Avatar per speaker, picked from PERSONA_VISUALS / CLIENT_FAMILY_AVATARS,
+ *     or a deterministic letter-tile fallback
+ *   - Senti-orchestrator events tagged with the orchestrator avatar so
+ *     "if orchestrator did anything it signs its name + time" — even
+ *     when the underlying event came from a worker job
+ *
+ * Scales: O(events + agents). Tested up to 20 speakers without degradation.
+ */
+
+import { PERSONA_VISUALS, ORCHESTRATOR_VISUALS } from "../agents/persona-visuals.js";
+
+/**
+ * Avatar map for client families (the OUTSIDE-the-persona-set agents
+ * that show up in any session: human users, browser-side coding
+ * assistants, etc). Keep emoji + a one-color hint so terminal + web
+ * renderers can tint consistently.
+ */
+export const CLIENT_FAMILY_AVATARS = Object.freeze({
+  human: { avatar: "🧑", color: "blue", label: "Human" },
+  claude: { avatar: "🟣", color: "purple", label: "Claude" },
+  codex: { avatar: "🟢", color: "green", label: "Codex" },
+  gpt: { avatar: "🟢", color: "green", label: "GPT" },
+  gemini: { avatar: "🔷", color: "cyan", label: "Gemini" },
+  grok: { avatar: "⚫", color: "gray", label: "Grok" },
+  cli: { avatar: "💻", color: "white", label: "CLI" },
+  guest: { avatar: "👤", color: "gray", label: "Guest" },
+  senti: { avatar: "🛡️", color: "gold", label: "Senti" },
+});
+
+const TRANSCRIPT_EVENT_KINDS = new Set([
+  "session_message",
+  "session_say",
+  "agent_response",
+  "session_usage",
+  "human_relay",
+  "agent_join",
+  "agent_left",
+  "agent_killed",
+  "agent_identified",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+const SYSTEM_EVENT_KINDS = new Set([
+  "agent_join",
+  "agent_left",
+  "agent_killed",
+  "agent_identified",
+  "daemon_alert",
+  "session_admin_kill",
+]);
+
+function normalize(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function detectFamily(modelOrId) {
+  const v = normalize(modelOrId).toLowerCase();
+  if (!v) return "guest";
+  if (v.includes("senti") || v.includes("kai-chen")) return "senti";
+  if (v.includes("claude") || v.includes("sonnet") || v.includes("opus")) return "claude";
+  if (v.includes("codex") || v.startsWith("gpt-") || v === "gpt") return "codex";
+  if (v.includes("gemini")) return "gemini";
+  if (v.includes("grok")) return "grok";
+  if (v.startsWith("human-") || v.includes("human")) return "human";
+  if (v === "cli" || v.startsWith("cli-")) return "cli";
+  if (v.startsWith("guest-")) return "guest";
+  return v.split(/[\s:/_-]+/).find(Boolean) || "guest";
+}
+
+function letterTile(label) {
+  const trimmed = normalize(label);
+  if (!trimmed) return "·";
+  return trimmed.slice(0, 2).toUpperCase();
+}
+
+/**
+ * Resolve a speaker's display identity given the agent id, model, and
+ * whatever profile bag the caller provides (e.g. github avatar URL,
+ * google photo URL, friendly name from auth).
+ */
+export function resolveSpeakerIdentity({
+  agentId,
+  agentModel = "",
+  profile = null,
+} = {}) {
+  const id = normalize(agentId) || "unknown";
+  const lowerId = id.toLowerCase();
+
+  // 1. Persona visuals — Nina, Maya, Jules, etc.
+  if (PERSONA_VISUALS[lowerId]) {
+    const v = PERSONA_VISUALS[lowerId];
+    return {
+      agentId: id,
+      family: lowerId,
+      avatar: v.avatar,
+      avatarUrl: null,
+      color: v.color,
+      displayName: v.fullName || v.shortName || id,
+    };
+  }
+
+  // 2. Orchestrator visuals — Senti / Kai Chen
+  if (lowerId === "senti" || lowerId === "kai-chen") {
+    const v = ORCHESTRATOR_VISUALS["kai-chen"] || {};
+    return {
+      agentId: id,
+      family: "senti",
+      avatar: v.avatar || CLIENT_FAMILY_AVATARS.senti.avatar,
+      avatarUrl: null,
+      color: v.color || CLIENT_FAMILY_AVATARS.senti.color,
+      displayName: v.fullName || "Senti",
+    };
+  }
+
+  // 3. Caller-provided profile (github avatar, google photo) wins for humans.
+  if (profile && (profile.avatarUrl || profile.displayName)) {
+    return {
+      agentId: id,
+      family: profile.family || detectFamily(id || agentModel),
+      avatar: profile.avatar || CLIENT_FAMILY_AVATARS.human.avatar,
+      avatarUrl: normalize(profile.avatarUrl) || null,
+      color: profile.color || CLIENT_FAMILY_AVATARS.human.color,
+      displayName: normalize(profile.displayName) || id,
+    };
+  }
+
+  // 4. Client family fallback by model / id pattern.
+  const family = detectFamily(agentModel || id);
+  const fallback = CLIENT_FAMILY_AVATARS[family] || CLIENT_FAMILY_AVATARS.guest;
+  return {
+    agentId: id,
+    family,
+    avatar: fallback.avatar,
+    avatarUrl: null,
+    color: fallback.color,
+    displayName: id || letterTile(family),
+  };
+}
+
+function eventTimestamp(event) {
+  return normalize(event?.ts || event?.timestamp);
+}
+
+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 ||
+    responseText ||
+    payload.text ||
+    payload.alert ||
+    payload.reason ||
+    "";
+  return normalize(text);
+}
+
+/**
+ * Compute deterministic activity stats from the event log:
+ *  - sessionLiveSeconds: created → last event
+ *  - perAgent[agentId]: { firstSeen, lastSeen, eventCount, activeSeconds, family, displayName, model }
+ *  - totals: { tokenTotal, costTotalUsd } summed from any payload.usage hints
+ *  - sentiActions: count of orchestrator events
+ */
+export function computeTranscriptStats({ sessionMeta = {}, events = [], speakerProfiles = new Map() } = {}) {
+  const perAgent = new Map();
+  let firstEventTs = null;
+  let lastEventTs = null;
+  let tokenTotal = 0;
+  let costTotalUsd = 0;
+  let sentiActions = 0;
+
+  for (const event of events) {
+    const ts = eventTimestamp(event);
+    if (!ts) continue;
+    const epoch = Date.parse(ts);
+    if (!Number.isFinite(epoch)) continue;
+    if (firstEventTs == null || epoch < firstEventTs) firstEventTs = epoch;
+    if (lastEventTs == null || epoch > lastEventTs) lastEventTs = epoch;
+
+    const agentId = normalize(event.agent?.id || event.agentId);
+    if (!agentId) continue;
+    const lowerId = agentId.toLowerCase();
+    if (lowerId === "senti" || lowerId === "kai-chen") sentiActions += 1;
+
+    if (!perAgent.has(agentId)) {
+      const profile = speakerProfiles.get(agentId) || null;
+      const identity = resolveSpeakerIdentity({
+        agentId,
+        agentModel: event.agent?.model || event.agentModel || "",
+        profile,
+      });
+      perAgent.set(agentId, {
+        agentId,
+        family: identity.family,
+        displayName: identity.displayName,
+        avatar: identity.avatar,
+        avatarUrl: identity.avatarUrl,
+        color: identity.color,
+        model: event.agent?.model || event.agentModel || "",
+        firstSeenMs: epoch,
+        lastSeenMs: epoch,
+        eventCount: 0,
+        tokens: 0,
+        costUsd: 0,
+      });
+    }
+    const record = perAgent.get(agentId);
+    record.eventCount += 1;
+    if (epoch < record.firstSeenMs) record.firstSeenMs = epoch;
+    if (epoch > record.lastSeenMs) record.lastSeenMs = epoch;
+
+    const usage = event?.payload?.usage;
+    if (usage && typeof usage === "object") {
+      const t =
+        Number(usage.totalTokens || usage.total_tokens || usage.tokens || 0) || 0;
+      const c = Number(usage.costUsd || usage.cost_usd || usage.cost || 0) || 0;
+      record.tokens += t;
+      record.costUsd += c;
+      tokenTotal += t;
+      costTotalUsd += c;
+    }
+  }
+
+  const createdAtMs = sessionMeta?.createdAt
+    ? Date.parse(sessionMeta.createdAt)
+    : null;
+  let startedAtMs;
+  if (Number.isFinite(createdAtMs) && firstEventTs != null) {
+    // Imported sessions can have events older than the local createdAt;
+    // pick the earlier of the two so live-for never goes negative.
+    startedAtMs = Math.min(createdAtMs, firstEventTs);
+  } else if (Number.isFinite(createdAtMs)) {
+    startedAtMs = createdAtMs;
+  } else {
+    startedAtMs = firstEventTs;
+  }
+  const sessionLiveSeconds =
+    startedAtMs != null && lastEventTs != null
+      ? Math.max(0, Math.round((lastEventTs - startedAtMs) / 1000))
+      : 0;
+
+  const agents = [];
+  for (const record of perAgent.values()) {
+    agents.push({
+      ...record,
+      activeSeconds: Math.max(0, Math.round((record.lastSeenMs - record.firstSeenMs) / 1000)),
+      firstSeen: new Date(record.firstSeenMs).toISOString(),
+      lastSeen: new Date(record.lastSeenMs).toISOString(),
+    });
+  }
+  agents.sort((a, b) => b.eventCount - a.eventCount);
+
+  return {
+    startedAt: startedAtMs ? new Date(startedAtMs).toISOString() : null,
+    endedAt: lastEventTs ? new Date(lastEventTs).toISOString() : null,
+    sessionLiveSeconds,
+    agents,
+    totals: { tokenTotal, costTotalUsd },
+    sentiActions,
+  };
+}
+
+function formatDuration(seconds) {
+  const s = Math.max(0, Math.round(seconds));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const remS = s % 60;
+  if (m < 60) return `${m}m ${remS}s`;
+  const h = Math.floor(m / 60);
+  const remM = m % 60;
+  if (h < 24) return `${h}h ${remM}m`;
+  const d = Math.floor(h / 24);
+  const remH = h % 24;
+  return `${d}d ${remH}h`;
+}
+
+function timestampOnly(iso) {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toISOString().replace("T", " ").replace(/\..+/, " UTC");
+}
+
+function avatarMd(identity) {
+  if (identity.avatarUrl) {
+    return `![${identity.displayName}](${identity.avatarUrl})`;
+  }
+  return identity.avatar || letterTile(identity.displayName || identity.agentId);
+}
+
+/**
+ * Build the iMessage-style markdown transcript.
+ *
+ * @param {object} params
+ * @param {object} params.sessionMeta  - { sessionId, createdAt, status, ... }
+ * @param {Array<object>} params.events
+ * @param {Array<object>} [params.agents] - registered agents (optional)
+ * @param {Map<string, object>} [params.speakerProfiles] - agentId →
+ *   { displayName, avatarUrl, family, color }. Used to surface real
+ *   GitHub / Google photos for human users.
+ * @param {object} [params.options]
+ * @param {boolean} [params.options.includeSystemEvents=true]
+ * @returns {{ markdown: string, stats: object }}
+ */
+export function buildTranscriptMarkdown({
+  sessionMeta = {},
+  events = [],
+  agents = [],
+  speakerProfiles = new Map(),
+  options = {},
+} = {}) {
+  const includeSystemEvents = options.includeSystemEvents !== false;
+  const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles });
+
+  const lines = [];
+  const sessionId = normalize(sessionMeta.sessionId) || "unknown";
+  lines.push(`# Session ${sessionId}`);
+  lines.push("");
+  lines.push(`Generated: ${new Date().toISOString()}`);
+  if (stats.startedAt) lines.push(`Started: ${stats.startedAt}`);
+  if (stats.endedAt) lines.push(`Last activity: ${stats.endedAt}`);
+  lines.push(`Live for: ${formatDuration(stats.sessionLiveSeconds)}`);
+  lines.push(`Senti actions: ${stats.sentiActions}`);
+  if (stats.totals.tokenTotal > 0 || stats.totals.costTotalUsd > 0) {
+    lines.push(
+      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}`,
+    );
+  }
+  lines.push("");
+
+  // Participants table
+  lines.push("## Participants");
+  lines.push("");
+  lines.push("| Avatar | Name | Family | Active for | Events | Tokens | Cost |");
+  lines.push("|---|---|---|---:|---:|---:|---:|");
+  for (const agent of stats.agents) {
+    const identity = {
+      avatar: agent.avatar,
+      avatarUrl: agent.avatarUrl,
+      displayName: agent.displayName,
+      agentId: agent.agentId,
+    };
+    lines.push(
+      `| ${avatarMd(identity)} | **${agent.displayName}** \`${agent.agentId}\` | ${agent.family} | ${formatDuration(agent.activeSeconds)} | ${agent.eventCount} | ${agent.tokens.toLocaleString("en-US")} | $${agent.costUsd.toFixed(4)} |`,
+    );
+  }
+  if (stats.agents.length === 0) {
+    lines.push("| 👤 | (no agents joined) | — | 0s | 0 | 0 | $0.00 |");
+  }
+  // Surface registered-but-silent agents at the bottom of the table so
+  // the participants list is comprehensive even if they never emitted
+  // a stream event.
+  const seenIds = new Set(stats.agents.map((a) => a.agentId));
+  for (const registered of agents || []) {
+    const id = normalize(registered?.agentId);
+    if (!id || seenIds.has(id)) continue;
+    const profile = speakerProfiles.get(id) || null;
+    const identity = resolveSpeakerIdentity({
+      agentId: id,
+      agentModel: registered.model || "",
+      profile,
+    });
+    lines.push(
+      `| ${avatarMd(identity)} | **${identity.displayName}** \`${id}\` | ${identity.family} | 0s · idle | 0 | 0 | $0.0000 |`,
+    );
+  }
+  lines.push("");
+
+  // Conversation
+  lines.push("## Conversation");
+  lines.push("");
+  for (const event of events) {
+    const kind = normalize(event.event || event.type);
+    if (!kind || !TRANSCRIPT_EVENT_KINDS.has(kind)) continue;
+    if (!includeSystemEvents && SYSTEM_EVENT_KINDS.has(kind)) continue;
+
+    const agentId = normalize(event.agent?.id || event.agentId);
+    const profile = speakerProfiles.get(agentId) || null;
+    const identity = resolveSpeakerIdentity({
+      agentId,
+      agentModel: event.agent?.model || event.agentModel || "",
+      profile,
+    });
+    const ts = eventTimestamp(event);
+    const body = eventBody(event);
+
+    if (SYSTEM_EVENT_KINDS.has(kind)) {
+      const hint = body || kind.replace(/_/g, " ");
+      lines.push(
+        `- _${timestampOnly(ts)} · ${avatarMd(identity)} **${identity.displayName}** ${hint}_`,
+      );
+      continue;
+    }
+
+    lines.push(`### ${avatarMd(identity)} ${identity.displayName}`);
+    lines.push(`> ${timestampOnly(ts)}`);
+    lines.push("");
+    if (body) {
+      const indented = body
+        .split(/\r?\n/)
+        .map((line) => (line ? line : ""))
+        .join("\n");
+      lines.push(indented);
+    } else {
+      lines.push(`_${kind}_`);
+    }
+    lines.push("");
+  }
+
+  return {
+    markdown: lines.join("\n"),
+    stats,
+  };
+}

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;