Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

4.7 KB
Raw Blame
import type { SessionInfo, SessionStatus } from "@adelie/server/api";
import { isSessionUnread } from "./session-seen";
import type { SessionSeenState } from "./session-seen";
import { S } from "./strings";

/**
 * Visual state carried by a Session row / chat header. Three states, and `null` for "say
 * nothing at all" — which is the resting state of every row the user has nothing to act on.
 *
 * Background work is a separate facet (see sessionBackgroundTasks), not a fourth state: a
 * Session can be idle, read, and still own a dev server or a background subagent, and a row
 * has to say both at once.
 */
export type SessionActivity = "running" | "compacting" | "completedUnread" | null;

/**
 * The Session's glyph state.
 *
 * Live execution comes from the server (`running` / `compacting` / `idle`). A settled Session
 * only has something to say while its last reply is UNREAD — that read/unread distinction is
 * the client's, because the API models no read receipt (see session-seen.ts). Once read it
 * falls silent: the glyph is a notification, and a list where every finished row carries a
 * permanent marker tells the user nothing about where to look next.
 *
 * `hasTrace` is the server's own "a Task has been started" flag, already on every list row, and
 * it is still load-bearing even though read and never-ran now render identically. Unread is a
 * timestamp comparison against the read marker, and a Session created AFTER this browser first
 * saw the Project has no marker of its own — it falls back to the baseline, and its creation
 * time is later, so it reads as unread. Without this guard every brand-new conversation would
 * wear the "finished, go look" dot before it had ever run.
 */
export function sessionActivity(
  status: SessionStatus,
  hasTrace: boolean,
  unread: boolean,
): SessionActivity {
  // Status first: a live run reports itself even in the window before its Trace is recorded.
  if (status === "running") return "running";
  if (status === "compacting") return "compacting";
  if (!hasTrace) return null;
  return unread ? "completedUnread" : null;
}

/**
 * The state's words, for the activity glyph's accessible name and tooltip: the glyph carries no
 * text of its own, so each state needs a different name. Read at render time — `S` is a live
 * binding swapped per interface language.
 */
export function sessionActivityLabel(activity: Exclude<SessionActivity, null>): string {
  if (activity === "running") return S.chat.statusRunning;
  if (activity === "compacting") return S.chat.statusCompacting;
  return S.chat.statusCompletedUnread;
}

/**
 * How many background tasks the Session still owns — command processes running past their
 * yield window plus background subagents mid-round — or 0 when none. The server omits the
 * field entirely at zero and pushes every change on the user channel, so this is live data
 * on the row, not a snapshot from the last list fetch. It is independent of the activity
 * state above: the mark it drives sits beside the glyph, on an idle row as readily as on a
 * running one, and goes away the moment the last task ends.
 */
export function sessionBackgroundTasks(session: Pick<SessionInfo, "backgroundTasks">): number {
  const tasks = session.backgroundTasks;
  return tasks === undefined ? 0 : tasks.processes + tasks.subagents;
}

/** The subset of a row this function needs (a whole SessionInfo satisfies it). */
export type SessionActivityRow = Pick<
  SessionInfo,
  "sessionId" | "status" | "hasTrace" | "lastActiveAt" | "source"
>;

/**
 * The glyph one Session ROW draws: `sessionActivity` plus the two things only the list knows —
 * whether the user has looked at this Session since it last ran, and whether it is the
 * conversation currently open.
 *
 * Only a person's conversation (`source` `user`, or not yet known) is ever unread. A background
 * Session — API, scheduled, subagent or CLI — finishes without anyone waiting on it, so its row
 * shows no "new reply" mark; it still shows when it is running.
 *
 * The open conversation is never unread: the user is looking at it. The chat page reaches the
 * same conclusion by stamping the seen marker once a run settles under the user's eyes, but it
 * does so in an effect, one tick after the run-end event moved the row's `lastActiveAt` —
 * deciding it here from what is on screen keeps the glyph from flashing unread for that tick.
 */
export function sessionRowActivity(
  session: SessionActivityRow,
  seen: SessionSeenState,
  activeSessionId: string | null,
): SessionActivity {
  const unread =
    (session.source === undefined || session.source === "user") &&
    session.sessionId !== activeSessionId &&
    isSessionUnread(seen, session.sessionId, session.lastActiveAt);
  return sessionActivity(session.status, session.hasTrace, unread);
}