zidane-ui 9.0.4 → 9.1.3

package/dist/chat/headless/sidebar/query.js

@@ -0,0 +1,450 @@
+import "./types.js";
+import { DEFAULT_SPACE_ID, compileQuery, isExtensionSpaceId, readField, renderTemplate, resolveSessionSpace, validateGroupBy, validateQuery, validateSort } from "zidane/chat/pure";
+//#region src/chat/headless/sidebar/query.ts
+/**
+* The sidebar's query layer: what extensions contribute to it (spaces with a
+* base query, filters, sorts, groupings, row decorations and items) and the
+* user's view on top, evaluated by zidane's one session-query evaluator
+* (`zidane/chat/pure`), so every app lists the same rows for the same view.
+*
+* - Spaces: the user's (Settings › Spaces, saved views among them) merged
+*   with the extensions' (`<extension>/<id>`, read-only base query), then the
+*   switcher's own order and hidden spaces on top.
+* - Membership: a session tagged with a space is in it; a space with a query
+*   also lists every session its query matches.
+* - Saving a view as a space builds its query with `viewQuery` (`zidane/chat/pure`),
+*   the builder the terminal app uses too.
+* - The view layer: the agent filter and the contributed filters narrow the
+*   space's rows; a contributed (or the space's) sort and grouping replace
+*   the built-in ones while chosen.
+*
+* React-free.
+*/
+/** Nothing contributed. */
+const NO_SIDEBAR_CONTRIBUTIONS = {
+	spaces: [],
+	filters: [],
+	sorts: [],
+	groups: [],
+	decorations: [],
+	items: []
+};
+const TOKENS = {
+	spaces: "space",
+	filters: "sidebar-filter",
+	sorts: "sidebar-sort",
+	groups: "sidebar-group",
+	decorations: "sidebar-decoration",
+	items: "sidebar-row"
+};
+/**
+* The six sidebar token stores of an extensions host as one store: a new snapshot whenever one of them changes.
+*
+* @param items - The host's item stores (`ExtensionsHost.items`).
+*/
+function sidebarContributionsOf(items) {
+	const read = () => ({
+		spaces: items.space.get(),
+		filters: items["sidebar-filter"].get(),
+		sorts: items["sidebar-sort"].get(),
+		groups: items["sidebar-group"].get(),
+		decorations: items["sidebar-decoration"].get(),
+		items: items["sidebar-row"].get()
+	});
+	let current = read();
+	const fresh = () => {
+		const next = read();
+		if (!Object.keys(TOKENS).every((k) => next[k] === current[k])) current = next;
+		return current;
+	};
+	return {
+		get: fresh,
+		subscribe(onChange) {
+			const offs = Object.values(TOKENS).map((token) => items[token].subscribe(onChange));
+			return () => {
+				for (const off of offs) off();
+			};
+		}
+	};
+}
+/**
+* An extension's space as the sidebar lists it: read-only, its `newSession` defaults as the space's.
+*
+* @param entry - The space item.
+*/
+function extensionSpaceOf(entry) {
+	const wire = entry.item;
+	const defaults = wire.newSession ?? {};
+	const emoji = !wire.icon?.gui && wire.icon?.tui ? wire.icon.tui : void 0;
+	return {
+		id: wire.id,
+		name: wire.name,
+		query: wire.query,
+		extensionId: entry.extension,
+		readonly: true,
+		items: wire.items,
+		...wire.icon?.gui ? { glyph: wire.icon.gui } : {},
+		...emoji ? { icon: {
+			kind: "emoji",
+			value: emoji
+		} } : {},
+		...wire.groupBy ? { groupBy: wire.groupBy } : {},
+		...wire.sortBy ? { sortBy: [...wire.sortBy] } : {},
+		...defaults.providerKey && defaults.modelId ? {
+			providerKey: defaults.providerKey,
+			modelId: defaults.modelId
+		} : {},
+		...defaults.effort ? { effort: defaults.effort } : {},
+		...defaults.agentId ? { agentId: defaults.agentId } : {}
+	};
+}
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/** A saved view's query, grouping and sort as stored in the settings' space list, each checked. */
+function storedQueryFields(raw) {
+	if (!isRecord(raw)) return {};
+	const out = {};
+	if (raw.query !== void 0 && validateQuery(raw.query).length === 0) out.query = raw.query;
+	if (raw.groupBy !== void 0 && validateGroupBy(raw.groupBy).length === 0) out.groupBy = raw.groupBy;
+	if (Array.isArray(raw.sortBy) && raw.sortBy.length > 0 && validateSort(raw.sortBy).length === 0) out.sortBy = raw.sortBy;
+	if (raw.hidden === true) out.hidden = true;
+	return out;
+}
+/**
+* The spaces the sidebar knows: the user's in their order (a saved view's query kept), then the
+* extensions' by `order`. A space the host already lists under an extension's id takes the
+* extension's base and keeps its place; one with an extension space's id (`<extension>/<id>`) whose
+* extension contributes it no more is dropped, as core and the terminal app drop it.
+*
+* @param user - The user's spaces, normalized (`normalizeSpaces`).
+* @param stored - The settings' space list as stored, for what normalizing dropped (a saved view's query).
+* @param extension - The extensions' space items.
+*/
+function mergeSidebarSpaces(user, stored, extension) {
+	const raw = /* @__PURE__ */ new Map();
+	for (const entry of Array.isArray(stored) ? stored : []) if (isRecord(entry) && typeof entry.id === "string" && !raw.has(entry.id.trim())) raw.set(entry.id.trim(), entry);
+	const fromExtensions = new Map([...extension].map((entry, index) => ({
+		entry,
+		index
+	})).sort((a, b) => a.entry.item.order - b.entry.item.order || a.index - b.index).map(({ entry }) => [entry.item.id, extensionSpaceOf(entry)]));
+	const out = [];
+	const placed = /* @__PURE__ */ new Set();
+	for (const space of user) {
+		const stub = raw.get(space.id);
+		const own = fromExtensions.get(space.id);
+		const fields = storedQueryFields(stub);
+		if (own) {
+			out.push(fields.hidden ? {
+				...own,
+				hidden: true
+			} : own);
+			placed.add(space.id);
+		} else if (isExtensionSpaceId(space.id) || isRecord(stub) && typeof stub.extensionId === "string") continue;
+		else out.push({
+			...space,
+			...fields
+		});
+	}
+	for (const [id, space] of fromExtensions) if (!placed.has(id)) out.push(space);
+	return out;
+}
+/**
+* The switcher's spaces: the user's order first (ids it names), the rest in their own order, the
+* hidden ones left out. The default space never hides, so the switcher always has one.
+*
+* @param spaces - Every space.
+* @param prefs - The switcher's order and hidden spaces.
+*/
+function switcherSpaces(spaces, prefs) {
+	const byId = new Map(spaces.map((s) => [s.id, s]));
+	const named = prefs.order.flatMap((id) => byId.has(id) ? [byId.get(id)] : []);
+	const seen = new Set(named.map((s) => s.id));
+	const ordered = [...named, ...spaces.filter((s) => !seen.has(s.id))];
+	const hidden = new Set(prefs.hidden);
+	return ordered.filter((s) => s.id === DEFAULT_SPACE_ID || !(s.hidden || hidden.has(s.id)));
+}
+/** A query that throws (an invalid one past validation) matches nothing rather than taking the list down. */
+function safeCompile(query, now) {
+	try {
+		return compileQuery(query, now === void 0 ? {} : { now });
+	} catch {
+		return () => false;
+	}
+}
+/**
+* Which sessions a space lists, or `null` while spaces are off (every session). A session tagged
+* with the space is in it (an unknown tag reads as the default space); a space with a query also
+* lists the sessions it matches. The orchestration Main is in every space.
+*
+* @param space - The space shown.
+* @param spaces - Every space.
+* @param spacesOn - Spaces are on.
+* @param now - Clock for relative times in the query.
+*/
+function spaceMembership(space, spaces, spacesOn, now) {
+	if (!spacesOn) return null;
+	const target = resolveSessionSpace(space.id, spaces);
+	const tagged = (row) => row.isMain === true || resolveSessionSpace(row.spaceId, spaces) === target;
+	if (!space.query) return tagged;
+	const matches = safeCompile(space.query, now);
+	return (row) => tagged(row) || matches(row);
+}
+/**
+* The contributed filters a space offers: those for every space and those naming it.
+*
+* @param filters - Every filter item.
+* @param spaceId - The space shown.
+*/
+function filtersForSpace(filters, spaceId) {
+	return filters.filter((f) => f.item.spaces === "all" || f.item.spaces.includes(spaceId));
+}
+/**
+* The query one contributed filter applies at the value the user picked, or `null` (off, or an
+* option no longer offered). A multi filter keeps a session one of its picked options matches.
+*
+* @param filter - The filter's wire form.
+* @param value - What the user picked.
+*/
+function filterQueryOf(filter, value) {
+	if (value === void 0 || value === false) return null;
+	if (filter.kind === "toggle") return value === true && filter.query ? filter.query : null;
+	const options = filter.options ?? [];
+	if (filter.kind === "select") {
+		const option = typeof value === "string" ? options.find((o) => o.id === value) : void 0;
+		return option ? option.query : null;
+	}
+	const picked = Array.isArray(value) ? options.filter((o) => value.includes(o.id)) : [];
+	return picked.length > 0 ? { any: picked.map((o) => o.query) } : null;
+}
+/**
+* The view layer's own narrowing: the agent and the contributed filters the space offers. `null`
+* when none applies.
+*
+* @param view - The space's view.
+* @param filters - The filters the space offers ({@link filtersForSpace}).
+* @param now - Clock for relative times.
+*/
+function viewFilterOf(view, filters, now) {
+	const tests = [];
+	const agent = view.agent ?? null;
+	if (agent !== null) tests.push((row) => row.agentId === agent);
+	const values = view.extension?.filters ?? {};
+	for (const { item } of filters) {
+		const query = filterQueryOf(item, values[item.id]);
+		if (query) {
+			const test = safeCompile(query, now);
+			tests.push((row) => test(row));
+		}
+	}
+	if (tests.length === 0) return null;
+	return (row) => tests.every((t) => t(row));
+}
+/** The agent grouping as a query grouping. */
+const AGENT_GROUPING = { field: "agentId" };
+/**
+* The grouping that applies: a contributed one the user picked, else the space's own (unless the
+* user picked a built-in one, {@link VIEW_CHOICE}), else the view's `groupBy` ('agent' as a query grouping).
+*
+* @param view - The space's view.
+* @param space - The space shown.
+* @param groups - Every contributed grouping.
+*/
+function resolveGrouping(view, space, groups) {
+	const picked = view.extension?.group;
+	const contributed = picked ? groups.find((g) => g.item.id === picked) : void 0;
+	if (contributed) return {
+		kind: "query",
+		groupBy: contributed.item.groupBy,
+		source: "extension",
+		id: contributed.item.id
+	};
+	if (space.groupBy && picked !== "@view") return {
+		kind: "query",
+		groupBy: space.groupBy,
+		source: "space"
+	};
+	if (view.groupBy === "agent") return {
+		kind: "query",
+		groupBy: AGENT_GROUPING,
+		source: "agent"
+	};
+	return {
+		kind: "builtin",
+		groupBy: view.groupBy
+	};
+}
+/**
+* The sort that applies: a contributed one the user picked, else the space's own (unless the user
+* picked a built-in one, {@link VIEW_CHOICE}). `null`: the view's `sortBy`.
+*
+* @param view - The space's view.
+* @param space - The space shown.
+* @param sorts - Every contributed sort.
+*/
+function resolveSort(view, space, sorts) {
+	const picked = view.extension?.sort;
+	const contributed = picked ? sorts.find((s) => s.item.id === picked) : void 0;
+	if (contributed) return contributed.item.sortBy;
+	if (space.sortBy && picked !== "@view") return space.sortBy;
+	return null;
+}
+/** The most chips a row shows, whatever the decorations add. */
+const MAX_ROW_CHIPS = 8;
+/** One chip per value: a list facet gives one per element; nothing for a missing value. */
+function chipTexts(value) {
+	return (Array.isArray(value) ? value : [value]).flatMap((v) => v === null || v === void 0 || v === "" ? [] : [typeof v === "object" ? JSON.stringify(v) : String(v)]);
+}
+/**
+* The decorator for a set of decorations: each session's merged decoration, or `null` when none
+* matches. The first matching decoration gives the icon, tone, subtitle and component; every one
+* adds its chips. Templates render with `renderTemplate`.
+*
+* The output is cached per session object: the same row object gets the same decoration object
+* back, so a row whose session didn't change keeps its memo. A row patched with new facets is a
+* new object and is decorated again. Relative times in `where` are read when a row is first
+* decorated: a new decorator (new decorations) reads them again.
+*
+* @param decorations - Every decoration item, in the host's order.
+* @param now - Clock for relative times in `where`.
+*/
+function createDecorator(decorations, now) {
+	if (decorations.length === 0) return () => null;
+	const compiled = decorations.map((entry) => ({
+		entry,
+		match: entry.item.where ? safeCompile(entry.item.where, now) : () => true
+	}));
+	const cache = /* @__PURE__ */ new WeakMap();
+	return (session) => {
+		if (cache.has(session)) return cache.get(session);
+		const decoration = decorate(session);
+		cache.set(session, decoration);
+		return decoration;
+	};
+	function decorate(session) {
+		const row = session;
+		let out = null;
+		const chips = [];
+		for (const { entry, match } of compiled) {
+			if (!match(row)) continue;
+			const { item } = entry;
+			out ??= { chips };
+			const ownIcon = item.icon?.gui && out.icon === void 0 ? item.icon.gui : void 0;
+			if (ownIcon) {
+				out.icon = ownIcon;
+				if (item.tone) out.tone = item.tone;
+			}
+			if (item.tone && out.tone === void 0) out.tone = item.tone;
+			if (item.subtitle && out.subtitle === void 0) {
+				const text = typeof item.subtitle === "string" ? item.subtitle : renderTemplate(item.subtitle.template, row);
+				if (text) out.subtitle = text;
+			}
+			const start = chips.length;
+			for (const chip of item.chips ?? []) {
+				const texts = "text" in chip ? [chip.text] : "template" in chip ? [renderTemplate(chip.template, row)].filter(Boolean) : chipTexts(readField(row, chip.facet));
+				const tone = chip.tone ?? item.tone;
+				for (const text of texts) {
+					if (chips.length >= 8) break;
+					chips.push({
+						text,
+						...tone ? { tone } : {},
+						...chip.icon?.gui ? { icon: chip.icon.gui } : {}
+					});
+				}
+			}
+			if (item.component && !out.component) out.component = {
+				extension: entry.extension,
+				component: item.component,
+				...ownIcon ? { icon: ownIcon } : {},
+				chips: chips.slice(start)
+			};
+		}
+		if (!out) return null;
+		return out.icon || out.subtitle || out.component || chips.length > 0 ? out : null;
+	}
+}
+/**
+* The items listed in a space: those naming it, where the space allows items (the default space
+* and user spaces always; an extension's when it says so).
+*
+* @param items - Every item.
+* @param space - The space shown.
+*/
+function itemsForSpace(items, space) {
+	if (space.extensionId && space.items !== true) return [];
+	return items.filter((e) => e.item.space === space.id);
+}
+/**
+* Each item with its child sessions (a session goes to the first item that claims it), and the
+* sessions no item claims.
+*
+* @param items - The space's items.
+* @param sessions - The sessions the space lists.
+* @param now - Clock for relative times.
+*/
+function claimChildSessions(items, sessions, now) {
+	const claimed = /* @__PURE__ */ new Set();
+	return {
+		items: items.map((entry) => {
+			const query = entry.item.children;
+			if (!query) return {
+				entry,
+				children: []
+			};
+			const match = safeCompile(query, now);
+			const children = sessions.filter((s) => !claimed.has(s.id) && match(s));
+			for (const s of children) claimed.add(s.id);
+			return {
+				entry,
+				children
+			};
+		}),
+		rest: claimed.size === 0 ? [...sessions] : sessions.filter((s) => !claimed.has(s.id))
+	};
+}
+/** A contributed filter's value that applies something (not off, not an empty pick). */
+const filterValueOn = (value) => value !== void 0 && value !== false && value !== "" && !(Array.isArray(value) && value.length === 0);
+/**
+* Whether the view narrows the space's sessions: an archive axis other than `active`, a project,
+* an activity window, an agent, or a contributed filter the space offers turned on. Grouping and
+* sort don't count.
+*
+* @param view - The space's view.
+* @param filters - The filters the space offers ({@link filtersForSpace}); a value kept for another one doesn't count.
+*/
+function viewFiltersOn(view, filters) {
+	if (view.archive !== "active" || view.project !== null || view.activity !== "all") return true;
+	if (view.agent) return true;
+	const values = view.extension?.filters ?? {};
+	return filters.some(({ item }) => filterValueOn(values[item.id]));
+}
+/**
+* The patch that turns every filter of a view off ({@link viewFiltersOn}), keeping its grouping,
+* sort and the contributed grouping and sort picked.
+*
+* @param view - The space's view.
+*/
+function clearedViewFilters(view) {
+	return {
+		archive: "active",
+		project: null,
+		activity: "all",
+		agent: null,
+		extension: {
+			...view.extension,
+			filters: {}
+		}
+	};
+}
+/**
+* The first saved-view name no space has yet: `nameOf(1)`, `nameOf(2)`…
+*
+* @param spaces - Every space.
+* @param nameOf - The name of the n-th saved view (`labels.savedViewName`).
+*/
+function nextSavedViewName(spaces, nameOf) {
+	const taken = new Set(spaces.map((s) => s.name));
+	let n = 1;
+	while (taken.has(nameOf(n))) n += 1;
+	return nameOf(n);
+}
+//#endregion
+export { AGENT_GROUPING, MAX_ROW_CHIPS, NO_SIDEBAR_CONTRIBUTIONS, claimChildSessions, clearedViewFilters, createDecorator, extensionSpaceOf, filterQueryOf, filtersForSpace, itemsForSpace, mergeSidebarSpaces, nextSavedViewName, resolveGrouping, resolveSort, sidebarContributionsOf, spaceMembership, switcherSpaces, viewFilterOf, viewFiltersOn };

package/dist/chat/headless/sidebar/rows.d.ts

@@ -1,6 +1,9 @@
+import { ExtensionItem } from "../../../extensions/headless/wire.js";
 import { SidebarGroupBy, SidebarListSession, SidebarSortBy } from "./types.js";
+import { SidebarItemEntry } from "./query.js";
 import { HostView } from "../hosts.js";
-import { SessionGroupBy, SessionListOptions, SessionListRow } from "../session-list.js";
+import { SessionGroupBy as SessionGroupBy$1, SessionListOptions, SessionListRow } from "../session-list.js";
+import { SessionGroupBy } from "zidane/chat/pure";
 //#region src/chat/headless/sidebar/rows.d.ts
 /**
  * The project a session is listed under: its repository's root, else its folder (`''`: none).
@@ -9,14 +12,36 @@ import { SessionGroupBy, SessionListOptions, SessionListRow } from "../session-l
  */
 declare function projectPathOf(session: Pick<SidebarListSession, 'projectRoot' | 'cwd'>): string;
 /** One row of the sidebar: a session-list row (a header may name its host) or a host's section header. */
-type SidebarRow<S extends SidebarListSession = SidebarListSession> = Exclude<SessionListRow<S>, {
-  kind: 'header';
+type SidebarListRow<S extends SidebarListSession = SidebarListSession> = Extract<SessionListRow<S>, {
+  kind: 'showMore';
 }> |
-/** A group header; a server's folder names its server (`hostId`), shown as a chip. */
+/** A session; `itemId`: listed under that extension item (one of its child sessions). */
+(Extract<SessionListRow<S>, {
+  kind: 'session';
+}> & {
+  itemId?: string;
+}) |
+/**
+ * An extension item listed among the sessions; its child sessions follow it (`itemId`) unless
+ * it is collapsed.
+ */
+{
+  kind: 'item';
+  id: string;
+  entry: ExtensionItem<'sidebar-row'>;
+  collapsed: boolean;
+  childCount: number;
+} |
+/**
+ * A group header; a server's folder names its server (`hostId`), shown as a chip. A project
+ * whose repository also has sessions on other machines names it (`repoKey`): those sessions
+ * are listed under it.
+ */
 (Extract<SessionListRow<S>, {
   kind: 'header';
 }> & {
   hostId?: string;
+  repoKey?: string;
 }) |
 /**
  * A host's section in the Per host view (This computer, then each saved
@@ -39,7 +64,7 @@ declare function groupsByFolder(groupBy: SidebarGroupBy): boolean;
 /** The directory-less bucket's label ("pure chat" sessions, no project). */
 declare const CHATS_BUCKET = "Chats";
 /** The list options {@link buildSidebarRows} passes through. */
-type BuildSidebarRowsOptions = Pick<SessionListOptions<SidebarListSession>, 'collapsedGroups' | 'showMoreExpanded' | 'idPrefix' | 'pinnedProjects'>;
+type BuildSidebarRowsOptions = Pick<SessionListOptions<SidebarListSession>, 'collapsedGroups' | 'showMoreExpanded' | 'idPrefix' | 'pinnedProjects' | 'compare'>;
 /**
  * Orchestration on: the main session is pulled out (pinned above the list).
  * Off: the main is not a chat; it is hidden, not regrouped.
@@ -60,13 +85,38 @@ declare function partitionMainSession<S extends SidebarListSession>(sessions: re
  * @param options - Collapsed groups, expanded "show more", id prefix, pinned projects.
  * @param project - The project a session groups under (defaults to {@link projectPathOf}).
  */
-declare function buildSidebarRows<S extends SidebarListSession>(sessions: S[], groupBy: SessionGroupBy, sortBy: SidebarSortBy, options?: BuildSidebarRowsOptions, project?: (session: S) => string): SidebarRow<S>[];
+declare function buildSidebarRows<S extends SidebarListSession>(sessions: S[], groupBy: SessionGroupBy$1, sortBy: SidebarSortBy, options?: BuildSidebarRowsOptions, project?: (session: S) => string): SidebarListRow<S>[];
+/**
+ * The group each repository's sessions share across machines, by `repoKey`. A
+ * repository with one local folder groups under that folder: its sessions on
+ * servers join it. A repository only on servers groups under its first
+ * server folder, in key order. A repository with several local folders (two
+ * clones) is left out: each folder keeps its own group, and so does each
+ * server folder.
+ *
+ * @param sessions - The listed sessions.
+ */
+declare function repoGroups(sessions: readonly SidebarListSession[]): Map<string, string>;
+/**
+ * Whether `session` is listed under a project header: a local session in its
+ * folder, or, for a header that names a `repoKey`, a server session of that
+ * repository.
+ *
+ * @param session - The session.
+ * @param project - The header's folder (`path`), its server (`hostId`) and its repository (`repoKey`).
+ */
+declare function isProjectMember(session: SidebarListSession, project: {
+  path: string;
+  hostId?: string;
+  repoKey?: string;
+}): boolean;
 /**
  * The sidebar's rows over every host. Per host: This computer's section
  * first, then each saved server's, each host's sessions grouped per folder
  * under its header. Any other view lists every host in one list, a server's
- * folder headers naming the server. Sessions of a server no longer saved are
- * not listed.
+ * folder headers naming the server, and a repository's sessions on every
+ * machine under one header ({@link repoGroups}). Sessions of a server no
+ * longer saved are not listed.
  *
  * @param sessions - The sessions to list.
  * @param hosts - This machine and each saved server, in order.
@@ -74,8 +124,40 @@ declare function buildSidebarRows<S extends SidebarListSession>(sessions: S[], g
  * @param sortBy - The order inside a group.
  * @param options - Collapsed groups, expanded "show more", pinned projects.
  */
-declare function buildHostSidebarRows<S extends SidebarListSession>(sessions: S[], hosts: readonly HostView[], groupBy: SidebarGroupBy, sortBy: SidebarSortBy, options?: BuildSidebarRowsOptions): SidebarRow<S>[];
-type SectionHeader<S extends SidebarListSession> = Extract<SidebarRow<S>, {
+declare function buildHostSidebarRows<S extends SidebarListSession>(sessions: S[], hosts: readonly HostView[], groupBy: Exclude<SidebarGroupBy, 'agent'>, sortBy: SidebarSortBy, options?: BuildSidebarRowsOptions): SidebarListRow<S>[];
+/**
+ * An item's row and its child sessions' rows (none while it is collapsed).
+ *
+ * @param item - The item and its child sessions.
+ * @param collapsedGroups - Collapsed row ids (an item collapses under its row id).
+ */
+declare function itemRows<S extends SidebarListSession>(item: SidebarItemEntry<S>, collapsedGroups?: ReadonlySet<string>): SidebarListRow<S>[];
+/** Options of {@link buildQuerySidebarRows}. */
+interface BuildQuerySidebarRowsOptions<S extends SidebarListSession> {
+  /** Collapsed header and item ids. */
+  collapsedGroups?: ReadonlySet<string>;
+  /** Labels by group key, under the grouping's own (agent names for the agent grouping). */
+  labels?: Readonly<Record<string, string>>;
+  /** The label of the group of sessions without a value. */
+  missingLabel?: string;
+  /** The favorites section's label. Default: the chat labels'. */
+  favoritesLabel?: string;
+  /** Favorited sessions lead the list under their own header, as in every grouping. */
+  isFavorite?: (session: S) => boolean;
+  /** Extension items, each listed first in the group its `group` names (no `group`: the group without a value). */
+  items?: readonly SidebarItemEntry<S>[];
+}
+/**
+ * The sidebar's rows under a query grouping (a space's, an extension's, the agents'): favorites
+ * first, then one group per value in the grouping's order, the items of each group leading it. A
+ * session whose value is a list is in each of its groups. The sessions come sorted.
+ *
+ * @param sessions - The sessions to list, in order.
+ * @param groupBy - The grouping.
+ * @param options - Collapse, labels, favorites and items.
+ */
+declare function buildQuerySidebarRows<S extends SidebarListSession>(sessions: readonly S[], groupBy: SessionGroupBy, options?: BuildQuerySidebarRowsOptions<S>): SidebarListRow<S>[];
+type SectionHeader<S extends SidebarListSession> = Extract<SidebarListRow<S>, {
   kind: 'header';
 } | {
   kind: 'host';
@@ -85,7 +167,7 @@ type SectionHeader<S extends SidebarListSession> = Extract<SidebarRow<S>, {
  * a header and the rows under it, drawn as its own `<ul>` so the header
  * sticks while they scroll by and the next section pushes it out.
  */
-type SidebarNode<S extends SidebarListSession = SidebarListSession> = Extract<SidebarRow<S>, {
+type SidebarNode<S extends SidebarListSession = SidebarListSession> = Extract<SidebarListRow<S>, {
   kind: 'session';
 } | {
   kind: 'showMore';
@@ -94,6 +176,15 @@ type SidebarNode<S extends SidebarListSession = SidebarListSession> = Extract<Si
   id: string;
   header: SectionHeader<S>;
   children: SidebarNode<S>[];
+} |
+/** An extension item and its child sessions' rows. */
+{
+  kind: 'item';
+  id: string;
+  row: Extract<SidebarListRow<S>, {
+    kind: 'item';
+  }>;
+  children: SidebarNode<S>[];
 };
 /**
  * The flat rows as nested sections: a host's section holds its groups, a
@@ -102,6 +193,6 @@ type SidebarNode<S extends SidebarListSession = SidebarListSession> = Extract<Si
  *
  * @param rows - The flat rows.
  */
-declare function nestSidebarRows<S extends SidebarListSession>(rows: readonly SidebarRow<S>[]): SidebarNode<S>[];
+declare function nestSidebarRows<S extends SidebarListSession>(rows: readonly SidebarListRow<S>[]): SidebarNode<S>[];
 //#endregion
-export { BuildSidebarRowsOptions, CHATS_BUCKET, SidebarNode, SidebarRow, buildHostSidebarRows, buildSidebarRows, groupsByFolder, nestSidebarRows, partitionMainSession, projectPathOf };
+export { BuildQuerySidebarRowsOptions, BuildSidebarRowsOptions, CHATS_BUCKET, SidebarListRow, SidebarNode, buildHostSidebarRows, buildQuerySidebarRows, buildSidebarRows, groupsByFolder, isProjectMember, itemRows, nestSidebarRows, partitionMainSession, projectPathOf, repoGroups };