A local-first multi-agent app development platform, built on PenguinHarness
/**
* Pure grouping logic for the chat sidebar's Session groups — the "by Workspace" mode
* (below), and the time buckets of the "by time" mode (TIME_BUCKETS, near the bottom).
*
* There is no Workspace entity on the server: a Session only carries the plain
* filesystem path locked in at creation (SessionInfo.workspace), so grouping works
* on those path strings. Sessions created without an explicit Workspace get an
* auto-created temporary workspace shaped like `<agentDir>/workspaces/tmp-<8hex>`
* (packages/core/src/internal/session-support.ts, createTempWorkspace); each of
* those is single-use, so per-path groups would be one-session noise — they are all
* merged into ONE trailing "temporary workspaces" group instead.
*/
import type { SessionCategory, SessionCategoryCounts, SessionInfo } from "@adelie/server/api";
/** Group key of the merged temporary-workspace group ("\0" can never appear in a filesystem path, so it never collides with a real Workspace). */
export const TEMP_WORKSPACE_GROUP_KEY = "\0temp-workspaces";
/** Auto-created temporary Workspace tail: `workspaces/tmp-<8hex>` (either path separator; core supports win32). */
const TEMP_WORKSPACE_RE = /[/\\]workspaces[/\\]tmp-[0-9a-f]{8}$/;
/**
* Any directory directly under an Agent's own `workspaces/` — `agents/<agent>/workspaces/<name>`
* — which is where the evaluation Skill creates its isolated Test Workspaces, one per Case ×
* Run, each holding that run's Test Session and nothing else. Their names are the Skill's
* own, so the parent directory is the rule, not a prefix; a directory below one of them is
* not itself such a Workspace. The server's workspace-group.ts folds the same paths, so the
* group the sidebar draws is the group it pages.
*/
const AGENT_WORKSPACES_RE = /[/\\]agents[/\\][^/\\]+[/\\]workspaces[/\\][^/\\]+$/;
/**
* Whether a Session's Workspace is one the system made for itself — core's auto-created
* temporary directory, or any directory directly under an Agent's `workspaces/` (the
* evaluation Skill's Test Workspaces) — and so belongs to the merged temp group instead of
* a group of its own. An empty path also counts as one: the server always backfills the
* resolved path, so this is defensive only.
*/
export function isTempWorkspace(workspace: string): boolean {
const p = workspace.trim();
return p === "" || TEMP_WORKSPACE_RE.test(p) || AGENT_WORKSPACES_RE.test(p);
}
/**
* Stable group key for a Session's Workspace (collapse state / React key): the path itself,
* or the temp sentinel — prefixed by the machine the directory is ON.
*
* A Workspace is a directory on a machine, so `/srv/app` on two machines is two different
* directories and the pair is the identity (the same rule workspace-registry.ts stores by,
* and the dashboard's rows follow). Keying on the path alone merged them into one folder
* whose "+" then opened a chat here, in whatever this machine has at that path.
*
* A machine of `null` — this server — keys exactly as it did before machines existed, which
* is what every persisted key already on a browser (collapse state, pin set, group order)
* was written as. `\0` appears in no path and in no machine id, so the two halves stay
* separable and neither can forge the other's shape.
*/
export function workspaceGroupKey(workspace: string, machineId: string | null = null): string {
const key = isTempWorkspace(workspace) ? TEMP_WORKSPACE_GROUP_KEY : workspace.trim();
return machineId === null ? key : `${machineId}\0${key}`;
}
/**
* The machine half of a group key; null for this server's own groups — including every key
* written before a group could name a machine, and the sentinel keys of the other grouping
* modes, which begin with the separator and so have no machine half.
*/
export function workspaceGroupMachine(groupKey: string): string | null {
const sep = groupKey.indexOf("\0");
return sep <= 0 ? null : groupKey.slice(0, sep);
}
/** The Workspace half of a group key: the path, or the temp sentinel. */
export function workspaceGroupPath(groupKey: string): string {
const sep = groupKey.indexOf("\0");
return sep <= 0 ? groupKey : groupKey.slice(sep + 1);
}
/**
* Query value that names a Workspace group to the server's list endpoint — the group's
* path, or the sentinel the server merges every auto-created temporary Workspace under
* (its `TEMP_WORKSPACE_GROUP`; stored Workspaces are realpath results and therefore
* absolute, so the bare word cannot collide with one). The machine half is dropped: the
* query goes TO that machine (the page key carries the source), and no server is asked
* about a path in another server's name.
*/
export function workspaceGroupQuery(groupKey: string): string {
const path = workspaceGroupPath(groupKey);
return path === TEMP_WORKSPACE_GROUP_KEY ? "temp" : path;
}
/** Short display label: the last path segment (the filesystem root yields "/"). */
export function workspaceLabel(workspace: string): string {
const parts = workspace
.trim()
.split(/[/\\]+/)
.filter(Boolean);
return parts[parts.length - 1] ?? "/";
}
/**
* Sidebar page size: sessions fetched per (Agent, category) per page, and the per-group
* display cap step for active rows — 10 conversations show by default and every "More"
* click reveals/loads 10 more. Fetches use limit = SIDEBAR_PAGE_SIZE + 1 (see splitPage)
* so one request both fills a page and answers "is there more" without a
* response-envelope change. Pages run in activity order (compareActivityDesc), cut at the
* watermark (cutAtWatermark) wherever several streams merge.
*/
export const SIDEBAR_PAGE_SIZE = 10;
/**
* Groups (Agents / Workspace groups) rendered per sidebar page. With dozens of groups the
* full list renders too tall to scan (#139), so the sidebar paginates them: one page at a
* time, stepped by the pager below the list. A pure display window — every group's data
* loading is unchanged, and the manual group order is committed over the whole sequence,
* not the page on screen.
*/
export const SIDEBAR_GROUP_PAGE_SIZE = 10;
/** Pages `total` groups take (always at least one, so an empty list still has a page 1). */
export function groupPageCount(total: number, pageSize = SIDEBAR_GROUP_PAGE_SIZE): number {
return Math.max(1, Math.ceil(total / pageSize));
}
/**
* A stored page number pinned inside the pages that currently exist. Groups come and go
* (a Workspace is removed, an Agent is deleted, a Project switch swaps the whole list),
* and a page that outlived its groups must land on the last real one rather than render
* an empty sidebar.
*/
export function clampGroupPage(
page: number,
total: number,
pageSize = SIDEBAR_GROUP_PAGE_SIZE,
): number {
return Math.min(Math.max(page, 0), groupPageCount(total, pageSize) - 1);
}
/** The page a group at `index` of the ordered sequence renders on (0-based both ends). */
export function groupPageOf(index: number, pageSize = SIDEBAR_GROUP_PAGE_SIZE): number {
return Math.floor(Math.max(index, 0) / pageSize);
}
/** The groups of one page, in the order given (the caller has already sorted them). */
export function groupPageSlice<T>(
groups: readonly T[],
page: number,
pageSize = SIDEBAR_GROUP_PAGE_SIZE,
): T[] {
const start = clampGroupPage(page, groups.length, pageSize) * pageSize;
return groups.slice(start, start + pageSize);
}
/**
* Conversations of one group that its reveal row still hides — what "Show N more chats"
* counts. Computed from the group's OWN numbers only: `loaded` rows are in memory,
* `shown` of them are past the display cap, and `total` is the group's exact server share
* — except once every Agent that could hold its rows is fully fetched (`fullyLoaded`),
* when the loaded rows ARE the share. That last clause is what keeps a count drifting
* above reality (totals refresh only on reload) from leaving a row that reveals nothing.
*/
export function hiddenRowCount({
shown,
loaded,
total,
fullyLoaded,
}: {
shown: number;
loaded: number;
total: number;
fullyLoaded: boolean;
}): number {
return Math.max((fullyLoaded ? loaded : Math.max(total, loaded)) - shown, 0);
}
/**
* The display window of one sidebar list — a group's active rows, or one of its
* collapsed folders; both obey the same rule and both read it from here. The list shows
* `SIDEBAR_PAGE_SIZE` rows, every "more" click reveals one page more, and a "show less"
* stands beside the reveal row (not after it) from the moment the list is revealed past
* its first page, folding it back to exactly that page. Rows beyond the cap stay in
* memory — a fetch that returned far more than a page (a time-mode folder fans out over
* every contributing Agent) is revealed a page at a time instead of all at once.
*
* `cap` is the list's current display cap, `loaded` the rows in memory, `total` its
* exact server share and `fullyLoaded` whether every Agent that could hold one of its
* rows is fetched out (see hiddenRowCount for why that last one decides the count).
* "Show less" needs both a raised cap and more loaded rows than a page — otherwise there
* is nothing for it to fold away.
*/
export function revealPlan({
cap,
loaded,
total,
fullyLoaded,
}: {
cap: number;
loaded: number;
total: number;
fullyLoaded: boolean;
}): { shown: number; hidden: number; canCollapse: boolean } {
const shown = Math.min(Math.max(cap, 0), loaded);
return {
shown,
hidden: hiddenRowCount({ shown, loaded, total, fullyLoaded }),
canCollapse: cap > SIDEBAR_PAGE_SIZE && loaded > SIDEBAR_PAGE_SIZE,
};
}
/**
* A row's place in the sidebar's activity order — the order every list of it is displayed
* AND paged in (the server's `order=activity`): last activity first, ties broken by id.
*/
export interface ActivityKey {
lastActiveAt: string;
sessionId: string;
}
/**
* The activity order: `lastActiveAt` descending, then `sessionId` descending, both compared by
* code point (`<` / `>`, never `localeCompare`). Negative when `a` is more recent.
*
* Code point because the two ends must agree on one total order: the browser names a page's
* cursor and the server slices on it, and a collation that ranks case or punctuation
* differently from the server would skip or repeat a row at every page boundary it touches.
* The stamps are uniform ISO-8601 UTC strings, so string order is time order.
*/
export function compareActivityDesc(a: ActivityKey, b: ActivityKey): number {
if (a.lastActiveAt !== b.lastActiveAt) return a.lastActiveAt > b.lastActiveAt ? -1 : 1;
if (a.sessionId !== b.sessionId) return a.sessionId > b.sessionId ? -1 : 1;
return 0;
}
/** The key alone, detached from the row — what a page position stores, so a later live event that moves the row does not move the cursor with it. */
export const activityKeyOf = (row: ActivityKey): ActivityKey => ({
lastActiveAt: row.lastActiveAt,
sessionId: row.sessionId,
});
/** The `before=` query value of a cursor: `<lastActiveAt>,<sessionId>` (neither half can contain a comma). */
export const activityCursorParam = (key: ActivityKey): string =>
`${key.lastActiveAt},${key.sessionId}`;
/** One server stream's position as the watermark sees it: the key of the last row read from it, and whether rows lie below that. */
export interface StreamPosition {
hasMore: boolean;
cursor: ActivityKey | null;
}
/**
* The watermark of a list merged from several streams (Agents, machines): the most recent
* cursor among the streams that still have more. Every row a stream has not served yet lies
* below its own cursor, so nothing missing can sort above this key — the rows at or above it
* are a true prefix of the merged order, and rows below it may still have unfetched rows
* between them.
*
* Null when no stream has more (everything is fetched; every loaded row shows). A stream with
* more but no cursor — nothing read from it yet — bounds nothing, so what is loaded still shows.
*/
export function activityWatermark(streams: readonly StreamPosition[]): ActivityKey | null {
let mark: ActivityKey | null = null;
for (const { hasMore, cursor } of streams) {
if (!hasMore || cursor === null) continue;
if (mark === null || compareActivityDesc(cursor, mark) < 0) mark = cursor;
}
return mark;
}
/**
* The rows a merged list shows: those at or above `watermark`, in activity order. `keep` (the
* open conversation) stays wherever it falls — a reader is never left looking at a chat its
* own list does not show. A null watermark keeps every row.
*
* The rows below are fetched but held back: showing them now would let a later page insert
* rows above them, and a list that grows anywhere but at its bottom reads as rows jumping.
*/
export function cutAtWatermark<T extends ActivityKey>(
rows: readonly T[],
watermark: ActivityKey | null,
keep?: string | null,
): T[] {
const kept =
watermark === null
? [...rows]
: rows.filter((r) => r.sessionId === keep || compareActivityDesc(r, watermark) <= 0);
return kept.sort(compareActivityDesc);
}
/**
* Applies the limit+1 fetch trick: `fetched` came from a request with `limit = pageSize + 1`;
* the visible page is the first `pageSize` items, and an overflow item (never shown) proves
* the server has more.
*/
export function splitPage<T>(fetched: T[], pageSize: number): { items: T[]; hasMore: boolean } {
return fetched.length > pageSize
? { items: fetched.slice(0, pageSize), hasMore: true }
: { items: fetched, hasMore: false };
}
/**
* The sidebar category a Session renders under — the same rule the server's `category`
* list filter applies, so filtered fetching and client rendering can never disagree. A
* company Session (company mode's desk and ticket Sessions) is in none, archived or not: only
* company mode's own views list it. Otherwise archived wins regardless of `source` (archiving
* is an explicit user action, so the Archived folder must show everything the user put there);
* then a person's conversation (`user`, or a row the server has not classified yet) is active,
* and every other source — API, scheduled, subagent and CLI Sessions — goes to the Background
* folder.
*/
export function sessionCategory(s: SessionInfo): SessionCategory | null {
if (s.source === "company") return null;
if (s.archived) return "archived";
return s.source === undefined || s.source === "user" ? "active" : "background";
}
/**
* Whether a Session matches the sidebar's live title search: case-insensitive substring
* over the stored title (untitled Sessions have none and never match a non-empty
* query); a blank/whitespace query matches everything (search inactive).
*/
export function matchesSessionQuery(s: SessionInfo, query: string): boolean {
const q = query.trim().toLowerCase();
if (q === "") return true;
return (s.title ?? "").toLowerCase().includes(q);
}
/** The collapsed-folder categories of a group, in render order (below the active user rows). */
export const FOLDER_CATEGORIES = ["background", "archived"] as const;
export type FolderCategory = (typeof FOLDER_CATEGORIES)[number];
/**
* Three-way split of one sidebar group's Sessions by sessionCategory (rendered top to
* bottom in this order): active user rows in the group body, then the collapsed
* Background and Archived folders.
*/
export type SessionPartition = Record<SessionCategory, SessionInfo[]>;
/**
* Partitions a group's Sessions for rendering. Input order is preserved within each part; a
* company Session, in no category, is in no part.
*/
export function partitionSessions(sessions: SessionInfo[]): SessionPartition {
const parts: SessionPartition = { active: [], background: [], archived: [] };
for (const s of sessions) {
const category = sessionCategory(s);
if (category !== null) parts[category].push(s);
}
return parts;
}
/**
* A group's FOLDED share: the conversations its collapsed folders hold (Background /
* Archived), summed from one set of category counts. Missing keys count as zero rather than
* poisoning the sum with NaN — the guard aggregateWorkspaceCounts applies to the same
* numbers.
*/
export function foldedShare(counts: SessionCategoryCounts): number {
let total = 0;
for (const category of FOLDER_CATEGORIES) {
const n = counts[category];
if (n > 0) total += n;
}
return total;
}
/**
* Whether a group holds nothing but folded conversations: no active row of its own, and at
* least one row inside its folders. That is the shape an evaluation leaves behind — one
* Workspace per Case × Run, each holding a single Test Session — and the shape of an Agent
* that has only ever been evaluated; the sidebar folds such a group up and sorts it behind
* the others. A group with both shares at zero (a registered but still unused Workspace) is
* NOT folder-only: it has nothing folded away to fold up.
*/
export function isFolderOnly(activeShare: number, folded: number): boolean {
return activeShare === 0 && folded > 0;
}
const ALL_CATEGORIES: readonly SessionCategory[] = ["active", ...FOLDER_CATEGORIES];
/** One workspace-mode group's aggregated server counts: exact totals plus which Agents hold rows of each category. */
export interface GroupCounts {
totals: SessionCategoryCounts;
/** Per category, the Agents whose share of this group is non-zero — the fetch fan-out set for the group's folders and "More". */
agents: Record<SessionCategory, string[]>;
}
/**
* Folds the per-Agent per-group category counts (SessionsResponse.workspaceCounts, keyed by
* the store into workspaceGroupKey form) into workspace-mode groups. The keys arrive
* machine-qualified because each machine answers about its own paths: summing two machines'
* counts for one path string would put both totals on both folders, each contradicting the
* rows under it. The sidebar labels a group's folders and decides its "More" from its own
* share — never from an Agent's other Workspaces, which would advertise folders whose
* content lives in other groups.
*/
export function aggregateWorkspaceCounts(
byAgent: ReadonlyMap<string, Readonly<Record<string, SessionCategoryCounts>>>,
): Map<string, GroupCounts> {
const out = new Map<string, GroupCounts>();
for (const [agentId, byGroup] of byAgent) {
for (const [key, counts] of Object.entries(byGroup)) {
let group = out.get(key);
if (!group) {
group = {
totals: { active: 0, background: 0, archived: 0 },
agents: { active: [], background: [], archived: [] },
};
out.set(key, group);
}
for (const category of ALL_CATEGORIES) {
const n = counts[category];
// !(n > 0) rather than n <= 0: a missing key (undefined) must not slip through and poison the totals with NaN.
if (!(n > 0)) continue;
group.totals[category] += n;
// Several temp paths of one Agent fold into the temp group: dedupe.
if (!group.agents[category].includes(agentId)) group.agents[category].push(agentId);
}
}
}
return out;
}
/**
* The Session the UI opens as "the last conversation" (the chat home's auto-select and
* the collapsed rail's entry): the loaded row the user was last IN — not the one created
* last, which on a revisited conversation is a different row. Only a person's conversation
* (an active row) qualifies: archived rows are hidden by choice, and neither a background
* Session — one an API caller, a scheduled task, a parent agent or `penguin run` opened — nor a
* company Session is a conversation of this list the user was in. Newest by lastActiveAt (stamped from `Date#toISOString`, so
* uniform ISO-8601 UTC like createdAt and comparable as a string), ties broken by sessionId —
* the list's ordering convention. Input order doesn't matter.
*/
export function latestConversation(sessions: readonly SessionInfo[]): SessionInfo | null {
let best: SessionInfo | null = null;
for (const s of sessions) {
if (sessionCategory(s) !== "active") continue;
if (
!best ||
s.lastActiveAt > best.lastActiveAt ||
(s.lastActiveAt === best.lastActiveAt && s.sessionId > best.sessionId)
) {
best = s;
}
}
return best;
}
/**
* Folds the per-Agent per-Workspace-path newest-Session stamps
* (SessionsResponse.workspaceLatest) into workspace-mode group keys: the newest across
* Agents, and across every temporary path for the merged temp group. createdAt is uniform
* ISO-8601 UTC, so the string maximum is the chronological one.
*/
export function aggregateWorkspaceLatest(
byAgent: ReadonlyMap<string, Readonly<Record<string, string>>>,
): Map<string, string> {
const out = new Map<string, string>();
for (const byWorkspace of byAgent.values()) {
for (const [workspace, createdAt] of Object.entries(byWorkspace)) {
const key = workspaceGroupKey(workspace);
const cur = out.get(key);
if (cur === undefined || createdAt > cur) out.set(key, createdAt);
}
}
return out;
}
export interface WorkspaceGroup<T = SessionInfo> {
/** Stable group key: the machine and the Workspace path (workspaceGroupKey), or the temp sentinel for the merged temp group — one per machine. */
key: string;
/** Display label: the path basename; empty for the temp group (the sidebar renders the localized name). */
label: string;
/** Full path for tooltips; null for the merged temp group (its members' paths all differ). */
fullPath: string | null;
/** The machine the directory is on; null for this server — a path is only a directory together with its machine. */
machineId: string | null;
/** True for the merged temporary-workspace group. */
temp: boolean;
/** Member Sessions, newest first (createdAt desc). */
sessions: T[];
}
/**
* Groups Sessions by their Workspace path. Named groups are sorted by their newest
* Session's createdAt desc; the merged temp group (if any) always comes last.
* Sessions inside a group are re-sorted newest first — the flat store list
* concatenates per-Agent server responses, so its order isn't globally chronological.
* createdAt is a uniform ISO-8601 UTC string (server: `new Date().toISOString()`),
* so lexicographic comparison equals chronological comparison.
* Generic over the row type (defaulting to SessionInfo, the sidebar's rows): the Trace
* page groups its own Session rows with the same logic — only `workspace` and the
* `createdAt` sort key are touched.
*
* Which machine a Session is on is asked of the caller rather than read off the row: the
* rows are the server's own SessionInfo, and where each one lives is the browser's fact,
* held by the map that routes every call about it (lib/session-machines.ts). The default
* says "this server", which is what a list of one server's Sessions is.
*/
export function groupSessionsByWorkspace<T extends { workspace: string; createdAt: string }>(
sessions: T[],
machineOf: (session: T) => string | null = () => null,
): WorkspaceGroup<T>[] {
const byKey = new Map<string, WorkspaceGroup<T>>();
for (const s of sessions) {
const machineId = machineOf(s);
const key = workspaceGroupKey(s.workspace, machineId);
let group = byKey.get(key);
if (!group) {
const temp = isTempWorkspace(s.workspace);
group = {
key,
label: temp ? "" : workspaceLabel(s.workspace),
fullPath: temp ? null : s.workspace.trim(),
machineId,
temp,
sessions: [],
};
byKey.set(key, group);
}
group.sessions.push(s);
}
const byCreatedDesc = (a: string, b: string) => (a < b ? 1 : a > b ? -1 : 0);
const groups = [...byKey.values()];
for (const g of groups) g.sessions.sort((a, b) => byCreatedDesc(a.createdAt, b.createdAt));
groups.sort((a, b) => {
if (a.temp !== b.temp) return a.temp ? 1 : -1;
return byCreatedDesc(a.sessions[0]?.createdAt ?? "", b.sessions[0]?.createdAt ?? "");
});
return groups;
}
/**
* Completes the session-derived grouping with every Workspace the server's counts know:
* a group the loaded pages touched no row of is added EMPTY (its rows page in down its own
* stream once it is on screen), and the named groups are re-sorted by recency — the newer
* of the group's newest loaded row and the server's `latest` stamp — with the merged temp
* group last, the order groupSessionsByWorkspace gives. Without this the group list was
* only as complete as each Agent's first page: a Workspace whose newest conversation was
* older than an Agent's ten newest never formed a group at all, which with dozens of
* Workspaces holding hundreds of conversations each is most of them.
*
* A counted key with no rows left in any category (its last conversation was deleted
* since the counts were taken) forms no group; a key already grouped keeps its loaded rows.
*/
export function completeWorkspaceGroups<T extends { createdAt: string }>(
groups: readonly WorkspaceGroup<T>[],
counts: ReadonlyMap<string, GroupCounts>,
latest: ReadonlyMap<string, string>,
): WorkspaceGroup<T>[] {
const out = [...groups];
const existing = new Set(groups.map((g) => g.key));
for (const [key, { totals }] of counts) {
if (existing.has(key)) continue;
if (!ALL_CATEGORIES.some((category) => totals[category] > 0)) continue;
existing.add(key);
// A counted key names a directory ON a machine, the way the loaded groups are keyed:
// its path half is what the label and the tooltip show, never the whole key.
const workspace = workspaceGroupPath(key);
const temp = workspace === TEMP_WORKSPACE_GROUP_KEY;
out.push({
key,
label: temp ? "" : workspaceLabel(workspace),
fullPath: temp ? null : workspace,
machineId: workspaceGroupMachine(key),
temp,
sessions: [],
});
}
// A group's newest loaded row (groupSessionsByWorkspace sorts members newest first) or
// the server's stamp, whichever is newer: a row added locally since the counts were
// taken counts, and so does a stamp for rows not loaded.
const recency = (g: WorkspaceGroup<T>): string => {
const loaded = g.sessions[0]?.createdAt ?? "";
const stamped = latest.get(g.key) ?? "";
return loaded > stamped ? loaded : stamped;
};
out.sort((a, b) => {
if (a.temp !== b.temp) return a.temp ? 1 : -1;
const ra = recency(a);
const rb = recency(b);
return ra < rb ? 1 : ra > rb ? -1 : 0;
});
return out;
}
/**
* The sidebar's time buckets, in render order: last day, last month, everything older.
* Bucketing is on `lastActiveAt` — the same key the recency sort and each row's compact
* timestamp already use, so a row labelled "3m ago" can never sit under "Earlier".
*/
export const TIME_BUCKETS = ["day", "month", "earlier"] as const;
export type TimeBucket = (typeof TIME_BUCKETS)[number];
const DAY_MS = 24 * 60 * 60 * 1000;
/** "Last month" is a rolling 30-day window, not a calendar month — the boundary a user reads off a relative timestamp. */
const MONTH_MS = 30 * DAY_MS;
/** Group key of a time bucket (collapse state / React key); "\0" can never appear in a Workspace path or an Agent id, so these never collide with the other modes' keys. */
export const timeGroupKey = (bucket: TimeBucket): string => `\0time-${bucket}`;
/**
* Group key the folders (Background / Archived) hang off in time mode. They are NOT bucketed:
* their rows load only when a folder is first expanded, so an unloaded Session's bucket is
* unknown and no bucket could honestly advertise a share of them. One shared, Project-wide set
* below the buckets is what the sidebar renders instead.
*/
export const TIME_FOLDERS_GROUP_KEY = "\0time-folders";
/** The bucket an activity timestamp falls in, against `nowMs`. An unparseable stamp counts as the oldest bucket rather than jumping to the top. */
export function timeBucketOf(lastActiveAt: string, nowMs: number): TimeBucket {
const t = Date.parse(lastActiveAt);
if (!Number.isFinite(t)) return "earlier";
const age = nowMs - t;
if (age < DAY_MS) return "day";
return age < MONTH_MS ? "month" : "earlier";
}
export interface TimeGroup<T = SessionInfo> {
/** Stable group key (timeGroupKey of the bucket). */
key: string;
bucket: TimeBucket;
/** Member Sessions, newest activity first. */
sessions: T[];
}
/**
* Buckets Sessions by their last activity into the three time groups, in TIME_BUCKETS
* order. Empty buckets are dropped — a "Last day" header over nothing states an absence
* the list is not asked to report. Members are sorted in activity order (compareActivityDesc;
* the flat store list merges per-Agent responses, so its order is not one to rely on); the
* sidebar re-orders them again for pins and manual sort. The caller has already cut the rows at
* the list's watermark, so a bucket only ever holds a prefix of the activity order.
*/
export function groupSessionsByTime<T extends ActivityKey>(
sessions: readonly T[],
nowMs: number,
): TimeGroup<T>[] {
const byBucket = new Map<TimeBucket, T[]>();
for (const s of sessions) {
const bucket = timeBucketOf(s.lastActiveAt, nowMs);
const list = byBucket.get(bucket);
if (list) list.push(s);
else byBucket.set(bucket, [s]);
}
const groups: TimeGroup<T>[] = [];
for (const bucket of TIME_BUCKETS) {
const rows = byBucket.get(bucket);
if (rows === undefined) continue;
rows.sort(compareActivityDesc);
groups.push({ key: timeGroupKey(bucket), bucket, sessions: rows });
}
return groups;
}
/** Sums per-Agent category totals into one Project-wide set (time mode's shared folders and its whole-list "More" read their share from it). */
export function totalCategoryCounts(
byAgent: ReadonlyMap<string, SessionCategoryCounts>,
): SessionCategoryCounts {
const totals: SessionCategoryCounts = { active: 0, background: 0, archived: 0 };
for (const counts of byAgent.values()) {
for (const category of ALL_CATEGORIES) {
const n = counts[category];
// Same guard as aggregateWorkspaceCounts: a missing key must not poison the sum with NaN.
if (n > 0) totals[category] += n;
}
}
return totals;
}
/**
* Stable pinned-first partition for sidebar groups: items whose key is in `pinned`
* come first, each partition preserving the input order (recency for Workspace
* groups, the configured order for Agents). Pure and mode-agnostic — callers pass
* the key extractor; pinned keys with no matching item are simply ignored.
*/
export function pinnedFirst<T>(
items: readonly T[],
keyOf: (item: T) => string,
pinned: ReadonlySet<string>,
): T[] {
if (pinned.size === 0) return [...items];
const pin: T[] = [];
const rest: T[] = [];
for (const item of items) (pinned.has(keyOf(item)) ? pin : rest).push(item);
return [...pin, ...rest];
}
/**
* The marks a Session an organization owns can carry — a desk session of one of its
* employees, or a session contributing to one of its tickets. `client` is stamped on the row
* when the organization runtime creates the Session and never changes, and a Session it opened
* is a `company` Session; `orgId` is resolved per read from the organization's own caches. All
* are optional on the wire, and a row is an organization's when any says so.
*/
export interface OrgSessionMarks {
/** The owning organization, resolved per read; absent once the organization is deleted. */
orgId?: string;
/** The client that created the Session; "org" is the organization runtime's own stamp. */
client?: string;
/** What kind of conversation it is; "company" for a desk or ticket Session. */
source?: string;
}
/**
* Whether a Session belongs to an organization. The durable stamp answers even after the
* organization is gone, which is the case `orgId` alone cannot: the caches it is read from no
* longer hold the Session, and the row would otherwise reappear somewhere it never belonged.
*/
export function isOrgSession(row: OrgSessionMarks): boolean {
return (
(row.orgId !== undefined && row.orgId !== "") ||
row.client === "org" ||
row.source === "company"
);
}
/**
* The rows the development list shows: the user's own conversations, ALWAYS. An
* organization's Sessions are driven by its scheduler rather than by the user, which is a
* fact about the Session and not about the shell around it — so neither company mode being
* switched off (the admin's master switch or the user's own) nor the organization being
* deleted turns one back into a conversation of this list. They are reached as themselves in
* company mode — a desk from the 工位 group, a ticket session from the ticket that started it
* — and stay reachable by their own url and through the Trace page regardless.
*
* The list's own fetches already leave these rows out, totals included (the server's
* `excludeOrg`); this is the guard for a row that enters by another door — the chat page's
* deep-link self-heal — and, applied at the source, it keeps such a row from conjuring the
* Workspace group, Agent group or time bucket it would belong to.
*/
export function withoutOrgSessions<T extends OrgSessionMarks>(rows: readonly T[]): T[] {
return rows.filter((s) => !isOrgSession(s));
}