Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Resources: packages, and what they hold

Simon Flack0065416db2be
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.test.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.test.ts
index 425fd8d04..aa64b365d 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.test.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.test.ts
@@ -23,6 +23,9 @@ const {
fetchLibraryItems,
fetchReferenceTypes,
updateLibraryItem,
+ addPackageMember,
+ fetchPackageMembers,
+ removePackageMember,
} = await import('./library-client');
const SERVER = {
@@ -125,6 +128,8 @@ describe('reading the library', () => {
urls: ['https://github.com/acme/switch'],
attachedRoomsCount: 2,
packageIds: ['pkg-1'],
+ referencesCount: 0,
+ documentsCount: 0,
createdAt: '2026-11-01T09:00:00+00:00',
});
});
@@ -278,3 +283,86 @@ describe('changing the library', () => {
expect(lastCall()).toMatchObject({ method: 'DELETE' });
});
});
+
+describe('packages', () => {
+ const PACKAGE = {
+ id: 'pkg-1',
+ owner_id: 'u1',
+ owner_name: 'Ada',
+ read_visibility: 'public',
+ write_visibility: 'private',
+ name: 'Onboarding',
+ description: 'Everything a new agent needs',
+ instructions: '',
+ references_count: 2,
+ documents_count: 1,
+ attached_rooms_count: 3,
+ created_at: '2026-11-01T09:00:00+00:00',
+ };
+
+ it('reads what a package holds, by kind, and a package’s counts', async () => {
+ fetchMock.mockImplementation(async () => jsonResponse([PACKAGE]));
+ const [pkg] = await fetchLibraryItems(SERVER, 'packages');
+ expect(pkg).toMatchObject({
+ kind: 'packages',
+ referencesCount: 2,
+ documentsCount: 1,
+ type: null,
+ });
+
+ fetchMock.mockImplementation(async () => jsonResponse([REFERENCE]));
+ const members = await fetchPackageMembers(SERVER, 'pkg-1', 'references');
+ expect(lastCall().url).toMatch(/\/gateway\/packages\/pkg-1\/references$/);
+ expect(members[0]).toMatchObject({ id: 'ref-1', kind: 'references', typeLabel: 'GitHub' });
+ });
+
+ it('creates a package with nothing of a reference’s or a document’s', async () => {
+ fetchMock.mockImplementation(async () => jsonResponse(PACKAGE));
+ await createLibraryItem(SERVER, 'packages', {
+ name: 'Onboarding',
+ description: '',
+ instructions: '',
+ readVisibility: 'public',
+ writeVisibility: 'private',
+ });
+ expect(lastCall().body).toEqual({
+ name: 'Onboarding',
+ description: '',
+ instructions: '',
+ read_visibility: 'public',
+ write_visibility: 'private',
+ });
+ });
+
+ it('adds with a POST and removes with a DELETE on the member’s path, saying which rooms lost it', async () => {
+ fetchMock.mockImplementation(async () => jsonResponse({}));
+ await addPackageMember(SERVER, 'pkg-1', 'documents', 'doc-1');
+ expect(lastCall()).toMatchObject({ method: 'POST' });
+ expect(lastCall().url).toMatch(/\/packages\/pkg-1\/documents\/doc-1$/);
+
+ fetchMock.mockImplementation(async () =>
+ jsonResponse({
+ package_id: 'pkg-1',
+ member_id: 'doc-1',
+ affected_room_ids: ['r1', 'r2'],
+ affected_room_names: ['design'],
+ hidden_affected_rooms_count: 1,
+ })
+ );
+ expect(await removePackageMember(SERVER, 'pkg-1', 'documents', 'doc-1')).toEqual({
+ affectedRoomNames: ['design'],
+ hiddenAffectedRoomsCount: 1,
+ });
+ expect(lastCall()).toMatchObject({ method: 'DELETE' });
+ });
+
+ it('counts no private rooms when an older server does not', async () => {
+ fetchMock.mockImplementation(async () =>
+ jsonResponse({ affected_room_ids: [], affected_room_names: [] })
+ );
+ expect(await removePackageMember(SERVER, 'pkg-1', 'references', 'ref-1')).toEqual({
+ affectedRoomNames: [],
+ hiddenAffectedRoomsCount: 0,
+ });
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.ts b/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.ts
index c3b37485a..e08175f35 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-servers/library-client.ts
@@ -7,6 +7,8 @@ import type {
LibraryItemRoom,
LibraryKind,
LibraryVisibility,
+ PackageMemberKind,
+ PackageMemberRemoval,
ReferenceTypeOption,
} from '@shared/core/switch-servers/library';
import type { SwitchServer } from '@shared/core/switch-servers/switch-servers';
@@ -30,6 +32,8 @@ type LibraryItemJson = {
value?: { urls?: unknown };
content?: string;
attached_rooms_count?: number;
+ references_count?: number;
+ documents_count?: number;
hidden_rooms_count?: number;
packages?: string[];
scope?: 'global' | 'room';
@@ -60,6 +64,8 @@ export function mapLibraryItem(kind: LibraryKind, r: LibraryItemJson): LibraryIt
attachedRoomsCount: r.attached_rooms_count ?? 0,
...(r.hidden_rooms_count !== undefined ? { hiddenRoomsCount: r.hidden_rooms_count } : {}),
packageIds: r.packages ?? [],
+ referencesCount: r.references_count ?? 0,
+ documentsCount: r.documents_count ?? 0,
createdAt: r.created_at,
};
}
@@ -195,3 +201,54 @@ export async function fetchReferenceTypes(server: SwitchServer): Promise<Referen
Number(b.isBuiltin) - Number(a.isBuiltin) || a.displayName.localeCompare(b.displayName)
);
}
+
+/** The references or documents a package holds (`GET /packages/{id}/{kind}`). */
+export async function fetchPackageMembers(
+ server: SwitchServer,
+ packageId: string,
+ kind: PackageMemberKind
+): Promise<LibraryItem[]> {
+ const res = await gatewayFetch(server, `${itemPath('packages', packageId)}/${kind}`, {
+ authenticated: true,
+ });
+ return ((await res.json()) as LibraryItemJson[]).map((r) => mapLibraryItem(kind, r));
+}
+
+/**
+ * Put a reference or document in a package. The server lets whoever may
+ * change the package do it, for an item the package's owner can read.
+ */
+export async function addPackageMember(
+ server: SwitchServer,
+ packageId: string,
+ kind: PackageMemberKind,
+ memberId: string
+): Promise<void> {
+ await gatewayFetch(
+ server,
+ `${itemPath('packages', packageId)}/${kind}/${encodeURIComponent(memberId)}`,
+ { authenticated: true, method: 'POST' }
+ );
+}
+
+/** Take a reference or document out of a package, saying which rooms lost it. */
+export async function removePackageMember(
+ server: SwitchServer,
+ packageId: string,
+ kind: PackageMemberKind,
+ memberId: string
+): Promise<PackageMemberRemoval> {
+ const res = await gatewayFetch(
+ server,
+ `${itemPath('packages', packageId)}/${kind}/${encodeURIComponent(memberId)}`,
+ { authenticated: true, method: 'DELETE' }
+ );
+ const json = (await res.json()) as {
+ affected_room_names?: string[];
+ hidden_affected_rooms_count?: number;
+ };
+ return {
+ affectedRoomNames: json.affected_room_names ?? [],
+ hiddenAffectedRoomsCount: json.hidden_affected_rooms_count ?? 0,
+ };
+}
diff --git a/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts b/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts
index 8a3d91a0b..f78450fb8 100644
--- a/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts
+++ b/console/apps/switch-console-desktop/src/main/core/workspaces/controller.ts
@@ -112,6 +112,9 @@ import {
fetchLibraryItems,
fetchReferenceTypes,
updateLibraryItem,
+ addPackageMember,
+ fetchPackageMembers,
+ removePackageMember,
} from '@main/core/switch-servers/library-client';
import { hostUnreachable } from '@main/core/switch-servers/require-server';
import { serverKindOf } from '@main/core/switch-servers/servers-store';
@@ -149,6 +152,8 @@ import type {
LibraryItemInput,
LibraryItemRoom,
LibraryKind,
+ PackageMemberKind,
+ PackageMemberRemoval,
ReferenceTypeOption,
} from '@shared/core/switch-servers/library';
import type {
@@ -1155,6 +1160,37 @@ export const workspacesController = createRPCController({
fetchLibraryItemRooms(server, params.kind, params.itemId)
),
+ /** The references or documents a package holds. */
+ listPackageMembers: (params: {
+ workspaceId: string;
+ packageId: string;
+ kind: PackageMemberKind;
+ }): Promise<LibraryItem[]> =>
+ withWorkspaceSession(params.workspaceId, (server) =>
+ fetchPackageMembers(server, params.packageId, params.kind)
+ ),
+
+ /** Put a reference or document in a package, or take it out. Refusals propagate in the gateway's words. */
+ addPackageMember: (params: {
+ workspaceId: string;
+ packageId: string;
+ kind: PackageMemberKind;
+ memberId: string;
+ }): Promise<void> =>
+ withReachableWorkspaceSession(params.workspaceId, (server) =>
+ addPackageMember(server, params.packageId, params.kind, params.memberId)
+ ),
+
+ removePackageMember: (params: {
+ workspaceId: string;
+ packageId: string;
+ kind: PackageMemberKind;
+ memberId: string;
+ }): Promise<PackageMemberRemoval> =>
+ withReachableWorkspaceSession(params.workspaceId, (server) =>
+ removePackageMember(server, params.packageId, params.kind, params.memberId)
+ ),
+
/** The types a new reference may be given. */
listReferenceTypes: (params: { workspaceId: string }): Promise<ReferenceTypeOption[]> =>
withWorkspaceSession(params.workspaceId, (server) => fetchReferenceTypes(server)),
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/library-card.tsx b/console/apps/switch-console-desktop/src/renderer/features/library/library-card.tsx
index 11aac0d0c..ea21c4bba 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/library/library-card.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/library-card.tsx
@@ -1,4 +1,4 @@
-import { DoorOpen, FileText, Link2, MoreVertical, Trash2 } from 'lucide-react';
+import { DoorOpen, FileText, Link2, MoreVertical, Package, Trash2 } from 'lucide-react';
import { Badge } from '@renderer/lib/ui/badge';
import { Button } from '@renderer/lib/ui/button';
import {
@@ -14,6 +14,7 @@ import {
accessOf,
LIBRARY_ACCESS_OPTIONS,
ownerText,
+ packageContentsText,
roomsText,
} from './library-model';
@@ -37,7 +38,9 @@ export function LibraryCard({
/** Null when you may not delete it. */
onDelete: (() => void) | null;
}) {
- const Icon = item.kind === 'references' ? Link2 : FileText;
+ const Icon = item.kind === 'references' ? Link2 : item.kind === 'packages' ? Package : FileText;
+ // What a package holds stands where a reference's type does.
+ const kindLine = item.kind === 'packages' ? packageContentsText(item) : item.typeLabel;
const mine = viewerId !== null && item.ownerId === viewerId;
const access = accessOf(item);
const owner = ownerText(item, viewerId);
@@ -62,9 +65,9 @@ export function LibraryCard({
{item.description || <span className="italic">No description.</span>}
</p>
<p className="flex min-w-0 items-center gap-1 text-xs text-foreground-muted">
- {item.typeLabel && (
+ {kindLine && (
<>
- <span className="truncate">{item.typeLabel}</span>
+ <span className="truncate">{kindLine}</span>
<span aria-hidden>·</span>
</>
)}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/library-item-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/library/library-item-view.tsx
index 6e5cd3758..088f4ffd5 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/library/library-item-view.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/library-item-view.tsx
@@ -63,6 +63,7 @@ import {
libraryRoomsKey,
referenceTypesKey,
} from './library-queries';
+import { PackageMembers } from './package-members';
function useViewParams() {
return useParams('libraryItem').params;
@@ -209,6 +210,14 @@ const LibraryItemPanel = observer(function LibraryItemPanel() {
<ItemBody item={data} />
)}
+ {data.kind === 'packages' && (
+ <PackageMembers
+ serverId={serverId}
+ workspaceId={workspaceId}
+ pkg={data}
+ canEdit={permissions.canEdit}
+ />
+ )}
<RoomsSection workspaceId={workspaceId} item={data} />
{data.packageIds.length > 0 && <PackagesLine workspaceId={workspaceId} item={data} />}
</Page>
@@ -647,7 +656,7 @@ export const libraryItemView = {
if (
typeof p.serverId !== 'string' ||
typeof p.itemId !== 'string' ||
- (p.kind !== 'references' && p.kind !== 'documents')
+ (p.kind !== 'references' && p.kind !== 'documents' && p.kind !== 'packages')
) {
return { ok: false, redirect: 'home', discardParams: true };
}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/library-model.test.ts b/console/apps/switch-console-desktop/src/renderer/features/library/library-model.test.ts
index 83d3b3580..fd1510989 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/library/library-model.test.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/library-model.test.ts
@@ -7,6 +7,8 @@ import {
libraryPermissions,
NO_LIBRARY_FILTER,
offeredLibraryFilter,
+ packageContentsText,
+ removalText,
parseUrls,
typeOptions,
visibilityOf,
@@ -28,6 +30,8 @@ function item(over: Partial<LibraryItem> = {}): LibraryItem {
urls: ['https://github.com/acme/switch'],
attachedRoomsCount: 0,
packageIds: [],
+ referencesCount: 0,
+ documentsCount: 0,
createdAt: '2026-11-01',
...over,
};
@@ -174,3 +178,24 @@ describe('the form', () => {
).toEqual({ urls: ['https://github.com/acme/switch', 'https://b'] });
});
});
+
+describe('a package', () => {
+ it('says what it holds in words', () => {
+ expect(packageContentsText({ referencesCount: 2, documentsCount: 1 })).toBe(
+ '2 references · 1 document'
+ );
+ expect(packageContentsText({ referencesCount: 1, documentsCount: 0 })).toBe('1 reference');
+ expect(packageContentsText({ referencesCount: 0, documentsCount: 0 })).toBe('Empty');
+ });
+
+ it('says which rooms lost an item taken out of it, counting the private ones', () => {
+ expect(removalText('Guide', { affectedRoomNames: [], hiddenAffectedRoomsCount: 0 })).toBe(
+ 'Removed Guide. No room had it only through this package.'
+ );
+ expect(
+ removalText('Guide', { affectedRoomNames: ['design'], hiddenAffectedRoomsCount: 2 })
+ ).toBe(
+ 'Removed Guide. These rooms had it only through this package, and no longer have it: design, 2 private rooms you can’t open.'
+ );
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/library-model.ts b/console/apps/switch-console-desktop/src/renderer/features/library/library-model.ts
index 0e185053b..387257151 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/library/library-model.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/library-model.ts
@@ -1,4 +1,5 @@
import type {
+ PackageMemberRemoval,
LibraryItem,
LibraryKind,
LibraryVisibility,
@@ -83,6 +84,12 @@ export const KIND_TEXT: Record<
Noun: 'Document',
none: 'No documents here yet. Write one to give your agents notes or instructions to share.',
},
+ packages: {
+ title: 'Packages',
+ noun: 'package',
+ Noun: 'Package',
+ none: 'No packages here yet. Make one to attach a set of references and documents to a room in one go.',
+ },
};
export type LibraryFilter = {
@@ -156,6 +163,32 @@ export function hiddenRoomsText(count: number): string {
return count === 1 ? '1 private room you can’t open' : `${count} private rooms you can’t open`;
}
+/** "2 references · 1 document", or "Empty" for a package holding nothing. */
+export function packageContentsText(item: Pick<LibraryItem, 'referencesCount' | 'documentsCount'>) {
+ const parts = [
+ item.referencesCount > 0
+ ? `${item.referencesCount} ${item.referencesCount === 1 ? 'reference' : 'references'}`
+ : null,
+ item.documentsCount > 0
+ ? `${item.documentsCount} ${item.documentsCount === 1 ? 'document' : 'documents'}`
+ : null,
+ ].filter(Boolean);
+ return parts.length > 0 ? parts.join(' · ') : 'Empty';
+}
+
export function roomsText(count: number): string {
return count === 0 ? 'In no rooms' : count === 1 ? 'In 1 room' : `In ${count} rooms`;
}
+
+/** What removing an item cost, in words: the rooms that lost it, the private ones counted. */
+export function removalText(name: string, removal: PackageMemberRemoval): string {
+ const hidden = removal.hiddenAffectedRoomsCount;
+ const rooms = [
+ ...removal.affectedRoomNames,
+ ...(hidden > 0
+ ? [hidden === 1 ? '1 private room you can’t open' : `${hidden} private rooms you can’t open`]
+ : []),
+ ];
+ if (rooms.length === 0) return `Removed ${name}. No room had it only through this package.`;
+ return `Removed ${name}. These rooms had it only through this package, and no longer have it: ${rooms.join(', ')}.`;
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/library-view.tsx b/console/apps/switch-console-desktop/src/renderer/features/library/library-view.tsx
index 652faa3b2..0684279ea 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/library/library-view.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/library-view.tsx
@@ -1,5 +1,5 @@
import { useQuery } from '@tanstack/react-query';
-import { FileText, Library, Link2, Plus } from 'lucide-react';
+import { FileText, Library, Link2, Package, Plus } from 'lucide-react';
import { observer } from 'mobx-react-lite';
import { useEffect, useState } from 'react';
import type { GuardResult, ViewDefinition } from '@renderer/app/view-registry';
@@ -42,6 +42,7 @@ const LibraryTitlebar = observer(function LibraryTitlebar() {
const KINDS = [
{ value: 'references', label: 'References', icon: Link2 },
{ value: 'documents', label: 'Documents', icon: FileText },
+ { value: 'packages', label: 'Packages', icon: Package },
] as const satisfies readonly { value: LibraryKind; label: string; icon: typeof Link2 }[];
const SCOPES = [
@@ -112,7 +113,7 @@ const LibraryPanel = observer(function LibraryPanel() {
) : (
<div className="flex flex-col gap-4">
<SegmentedControl
- ariaLabel="References or documents"
+ ariaLabel="References, documents or packages"
value={kind}
onChange={setKind}
options={KINDS}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/library/package-members.tsx b/console/apps/switch-console-desktop/src/renderer/features/library/package-members.tsx
new file mode 100644
index 000000000..d7558bddd
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/library/package-members.tsx
@@ -0,0 +1,364 @@
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { FileText, Link2, Loader2, Plus, Search, X } from 'lucide-react';
+import { type ReactNode, useState } from 'react';
+import { failureText } from '@renderer/lib/errors/describe-failure';
+import { rpc } from '@renderer/lib/ipc';
+import { useNavigate } from '@renderer/lib/layout/navigation-provider';
+import { Alert, AlertDescription } from '@renderer/lib/ui/alert';
+import { Button } from '@renderer/lib/ui/button';
+import {
+ Dialog,
+ DialogContent,
+ DialogContentArea,
+ DialogHeader,
+ DialogTitle,
+} from '@renderer/lib/ui/dialog';
+import { Input } from '@renderer/lib/ui/input';
+import type { LibraryItem, PackageMemberKind } from '@shared/core/switch-servers/library';
+import { KIND_TEXT, removalText } from './library-model';
+import { invalidateLibrary, libraryItemsKey } from './library-queries';
+
+export const packageMembersKey = (
+ workspaceId: string,
+ packageId: string,
+ kind: PackageMemberKind
+) => ['package-members', workspaceId, packageId, kind];
+
+/**
+ * What a package holds: its references and documents, each opening its own
+ * page. Whoever may change the package adds and removes them; taking one out
+ * says which rooms lost it.
+ */
+export function PackageMembers({
+ serverId,
+ workspaceId,
+ pkg,
+ canEdit,
+}: {
+ serverId: string;
+ workspaceId: string;
+ pkg: LibraryItem;
+ canEdit: boolean;
+}) {
+ const [notice, setNotice] = useState<string | null>(null);
+ return (
+ <>
+ {notice !== null && (
+ <Alert>
+ <AlertDescription className="flex items-start justify-between gap-3">
+ <span>{notice}</span>
+ <button
+ type="button"
+ aria-label="Dismiss"
+ className="cursor-pointer text-foreground-muted hover:text-foreground"
+ onClick={() => setNotice(null)}
+ >
+ <X className="size-3.5" />
+ </button>
+ </AlertDescription>
+ </Alert>
+ )}
+ {(['references', 'documents'] as const).map((kind) => (
+ <MemberSection
+ key={kind}
+ serverId={serverId}
+ workspaceId={workspaceId}
+ pkg={pkg}
+ kind={kind}
+ canEdit={canEdit}
+ onRemoved={setNotice}
+ />
+ ))}
+ </>
+ );
+}
+
+function MemberSection({
+ serverId,
+ workspaceId,
+ pkg,
+ kind,
+ canEdit,
+ onRemoved,
+}: {
+ serverId: string;
+ workspaceId: string;
+ pkg: LibraryItem;
+ kind: PackageMemberKind;
+ canEdit: boolean;
+ onRemoved: (notice: string) => void;
+}) {
+ const queryClient = useQueryClient();
+ const { navigate } = useNavigate();
+ const text = KIND_TEXT[kind];
+ const members = useQuery({
+ queryKey: packageMembersKey(workspaceId, pkg.id, kind),
+ queryFn: () => rpc.workspaces.listPackageMembers({ workspaceId, packageId: pkg.id, kind }),
+ });
+ const [adding, setAdding] = useState(false);
+ const [armed, setArmed] = useState<string | null>(null);
+ const [busy, setBusy] = useState<string | null>(null);
+ const [error, setError] = useState<string | null>(null);
+
+ async function remove(member: LibraryItem) {
+ setBusy(member.id);
+ setError(null);
+ try {
+ const removal = await rpc.workspaces.removePackageMember({
+ workspaceId,
+ packageId: pkg.id,
+ kind,
+ memberId: member.id,
+ });
+ onRemoved(removalText(member.name, removal));
+ await refreshAfterChange(queryClient, workspaceId, pkg.id, kind);
+ } catch (cause) {
+ setError(failureText(cause, `Could not remove ${member.name} from the package.`));
+ } finally {
+ setBusy(null);
+ setArmed(null);
+ }
+ }
+
+ return (
+ <section aria-label={text.title} className="flex flex-col gap-2.5">
+ <div className="flex min-h-7 items-center justify-between gap-3">
+ <h2 className="text-sm font-semibold text-foreground">{text.title} in this package</h2>
+ {canEdit && (
+ <Button size="sm" variant="outline" onClick={() => setAdding(true)}>
+ <Plus className="size-3.5" />
+ Add {text.noun}
+ </Button>
+ )}
+ </div>
+ {members.isPending ? (
+ <Loader2 className="size-4 animate-spin text-foreground-muted" />
+ ) : members.isError ? (
+ <p className="text-xs text-destructive">
+ {failureText(members.error, `Could not list the package’s ${text.title.toLowerCase()}.`)}
+ </p>
+ ) : members.data.length === 0 ? (
+ <p className="text-sm text-foreground-muted">No {text.title.toLowerCase()} in it yet.</p>
+ ) : (
+ <List>
+ {members.data.map((member) => (
+ <div key={member.id} className="flex items-center gap-2 px-3.5 py-2.5">
+ <button
+ type="button"
+ className="flex min-w-0 flex-1 cursor-pointer items-center gap-3 text-left"
+ onClick={() => navigate('libraryItem', { serverId, kind, itemId: member.id })}
+ >
+ {kind === 'references' ? (
+ <Link2 className="size-4 shrink-0 text-foreground-muted" />
+ ) : (
+ <FileText className="size-4 shrink-0 text-foreground-muted" />
+ )}
+ <span className="flex min-w-0 flex-col">
+ <span className="truncate text-sm text-foreground">{member.name}</span>
+ {(member.typeLabel || member.description) && (
+ <span className="truncate text-xs text-foreground-muted">
+ {[member.typeLabel, member.description].filter(Boolean).join(' · ')}
+ </span>
+ )}
+ </span>
+ </button>
+ {canEdit && armed === member.id ? (
+ <span className="flex shrink-0 items-center gap-1">
+ <span className="text-xs text-foreground-muted">
+ Rooms that have it only through this package lose it.
+ </span>
+ <Button
+ size="sm"
+ variant="ghost"
+ disabled={busy !== null}
+ onClick={() => setArmed(null)}
+ >
+ Keep
+ </Button>
+ <Button
+ size="sm"
+ variant="destructive"
+ disabled={busy !== null}
+ autoFocus
+ onClick={() => void remove(member)}
+ >
+ {busy === member.id ? <Loader2 className="animate-spin" /> : 'Remove'}
+ </Button>
+ </span>
+ ) : (
+ canEdit && (
+ <Button
+ variant="ghost"
+ size="icon-xs"
+ aria-label={`Remove ${member.name} from the package`}
+ title="Remove from the package"
+ disabled={busy !== null}
+ onClick={() => setArmed(member.id)}
+ >
+ <X />
+ </Button>
+ )
+ )}
+ </div>
+ ))}
+ </List>
+ )}
+ {error !== null && <p className="text-xs text-destructive">{error}</p>}
+ {adding && (
+ <AddMemberDialog
+ workspaceId={workspaceId}
+ pkg={pkg}
+ kind={kind}
+ inPackage={new Set((members.data ?? []).map((member) => member.id))}
+ onClose={() => setAdding(false)}
+ />
+ )}
+ </section>
+ );
+}
+
+/** The references or documents the viewer can read that the package does not hold yet. */
+function AddMemberDialog({
+ workspaceId,
+ pkg,
+ kind,
+ inPackage,
+ onClose,
+}: {
+ workspaceId: string;
+ pkg: LibraryItem;
+ kind: PackageMemberKind;
+ inPackage: Set<string>;
+ onClose: () => void;
+}) {
+ const queryClient = useQueryClient();
+ const text = KIND_TEXT[kind];
+ const items = useQuery({
+ queryKey: libraryItemsKey(workspaceId, kind),
+ queryFn: () => rpc.workspaces.listLibraryItems({ workspaceId, kind }),
+ });
+ const [filter, setFilter] = useState('');
+ const [done, setDone] = useState<Set<string>>(new Set());
+ const [busy, setBusy] = useState<string | null>(null);
+ const [error, setError] = useState<string | null>(null);
+ const needle = filter.trim().toLowerCase();
+ const shown = (items.data ?? [])
+ .filter((item) => !inPackage.has(item.id) && !done.has(item.id))
+ .filter(
+ (item) =>
+ !needle ||
+ item.name.toLowerCase().includes(needle) ||
+ item.description.toLowerCase().includes(needle)
+ )
+ .sort((a, b) => a.name.localeCompare(b.name));
+
+ async function add(item: LibraryItem) {
+ setBusy(item.id);
+ setError(null);
+ try {
+ await rpc.workspaces.addPackageMember({
+ workspaceId,
+ packageId: pkg.id,
+ kind,
+ memberId: item.id,
+ });
+ setDone((current) => new Set(current).add(item.id));
+ await refreshAfterChange(queryClient, workspaceId, pkg.id, kind);
+ } catch (cause) {
+ setError(failureText(cause, `Could not add ${item.name} to the package.`));
+ } finally {
+ setBusy(null);
+ }
+ }
+
+ return (
+ <Dialog open onOpenChange={(open) => !open && onClose()}>
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle>
+ Add {text.title.toLowerCase()} to {pkg.name}
+ </DialogTitle>
+ </DialogHeader>
+ <DialogContentArea className="flex flex-col gap-3 pt-0">
+ <div className="relative">
+ <Search className="absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-foreground-muted" />
+ <Input
+ autoFocus
+ className="pl-8"
+ placeholder={`Search ${text.title.toLowerCase()}…`}
+ value={filter}
+ onChange={(event) => setFilter(event.target.value)}
+ />
+ </div>
+ {items.isPending ? (
+ <Loader2 className="size-4 animate-spin text-foreground-muted" />
+ ) : items.isError ? (
+ <p className="text-xs text-destructive">
+ {failureText(items.error, `Could not list the ${text.title.toLowerCase()}.`)}
+ </p>
+ ) : shown.length === 0 ? (
+ <p className="text-sm text-foreground-muted">
+ {needle
+ ? `No ${text.noun} matches.`
+ : `Every ${text.noun} you can see is already in it.`}
+ </p>
+ ) : (
+ <div className="flex max-h-80 flex-col overflow-y-auto">
+ {shown.map((item) => (
+ <div key={item.id} className="flex items-center gap-2 py-1.5">
+ <span className="flex min-w-0 flex-1 flex-col">
+ <span className="truncate text-sm text-foreground">{item.name}</span>
+ {(item.typeLabel || item.description) && (
+ <span className="truncate text-xs text-foreground-muted">
+ {[item.typeLabel, item.description].filter(Boolean).join(' · ')}
+ </span>
+ )}
+ </span>
+ <Button
+ size="sm"
+ variant="outline"
+ disabled={busy !== null}
+ onClick={() => void add(item)}
+ >
+ {busy === item.id ? <Loader2 className="animate-spin" /> : 'Add'}
+ </Button>
+ </div>
+ ))}
+ </div>
+ )}
+ {error !== null && <p className="text-xs text-destructive">{error}</p>}
+ <p className="text-xs text-foreground-muted">
+ The server takes only what the package’s owner can see.
+ </p>
+ <div className="flex justify-end">
+ <Button size="sm" variant="outline" onClick={onClose}>
+ Done
+ </Button>
+ </div>
+ </DialogContentArea>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+/** A package's contents changed: its members, counts, and the items' own "in packages" read again. */
+async function refreshAfterChange(
+ queryClient: ReturnType<typeof useQueryClient>,
+ workspaceId: string,
+ packageId: string,
+ kind: PackageMemberKind
+): Promise<void> {
+ await Promise.all([
+ queryClient.invalidateQueries({ queryKey: packageMembersKey(workspaceId, packageId, kind) }),
+ invalidateLibrary(queryClient, workspaceId, 'packages'),
+ invalidateLibrary(queryClient, workspaceId, kind),
+ ]);
+}
+
+function List({ children }: { children: ReactNode }) {
+ return (
+ <div className="divide-y divide-border overflow-hidden rounded-[10px] border border-border">
+ {children}
+ </div>
+ );
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/tests/browser/library-view.test.tsx b/console/apps/switch-console-desktop/src/renderer/tests/browser/library-view.test.tsx
index 828bd9ab7..f4b89bc4d 100644
--- a/console/apps/switch-console-desktop/src/renderer/tests/browser/library-view.test.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/tests/browser/library-view.test.tsx
@@ -20,7 +20,7 @@ vi.hoisted(() => {
const state = vi.hoisted(() => ({
params: {} as Record<string, unknown>,
- items: { references: [] as unknown[], documents: [] as unknown[] },
+ items: { references: [] as unknown[], documents: [] as unknown[], packages: [] as unknown[] },
item: null as unknown,
rooms: [] as { roomId: string; roomName: string }[],
admin: false,
@@ -34,6 +34,9 @@ const rpcMock = vi.hoisted(() => ({
listLibrary: vi.fn(),
deleteLibraryItem: vi.fn(),
setRoomResourceAttached: vi.fn(),
+ listPackageMembers: vi.fn(),
+ addPackageMember: vi.fn(),
+ removePackageMember: vi.fn(),
}));
const showModal = vi.hoisted(() => vi.fn());
const navigate = vi.hoisted(() => vi.fn());
@@ -100,6 +103,8 @@ function item(over: Partial<LibraryItem>): LibraryItem {
urls: ['https://github.com/acme/switch'],
attachedRoomsCount: 1,
packageIds: [],
+ referencesCount: 0,
+ documentsCount: 0,
createdAt: '2026-11-01',
...over,
};
@@ -126,11 +131,23 @@ beforeEach(() => {
documents: [
item({ id: 'doc-1', kind: 'documents', name: 'Style guide', type: null, typeLabel: null }),
],
+ packages: [
+ item({
+ id: 'pkg-1',
+ kind: 'packages',
+ name: 'Onboarding',
+ type: null,
+ typeLabel: null,
+ urls: [],
+ referencesCount: 2,
+ documentsCount: 1,
+ }),
+ ],
};
state.rooms = [{ roomId: 'room-1', roomName: 'design' }];
for (const fn of Object.values(rpcMock)) fn.mockReset();
rpcMock.listLibraryItems.mockImplementation(
- async ({ kind }: { kind: 'references' | 'documents' }) => state.items[kind]
+ async ({ kind }: { kind: 'references' | 'documents' | 'packages' }) => state.items[kind]
);
rpcMock.getLibraryItem.mockImplementation(async () => state.item);
rpcMock.listLibraryItemRooms.mockImplementation(async () => state.rooms);
@@ -147,6 +164,14 @@ beforeEach(() => {
rpcMock.deleteLibraryItem.mockResolvedValue({ detachedRoomIds: [], affectedPackageIds: [] });
rpcMock.updateLibraryItem.mockResolvedValue({});
rpcMock.setRoomResourceAttached.mockResolvedValue(undefined);
+ rpcMock.listPackageMembers.mockImplementation(async ({ kind }: { kind: string }) =>
+ kind === 'references' ? [state.items.references[0]] : []
+ );
+ rpcMock.addPackageMember.mockResolvedValue(undefined);
+ rpcMock.removePackageMember.mockResolvedValue({
+ affectedRoomNames: ['design'],
+ hiddenAffectedRoomsCount: 1,
+ });
showModal.mockReset();
navigate.mockReset();
});
@@ -452,3 +477,69 @@ describe('deleting', () => {
expect(dialogText()).toContain('It is removed from 1 private room you can’t open.');
});
});
+
+describe('a package', () => {
+ beforeEach(() => {
+ state.params = { serverId: 'srv', kind: 'packages', itemId: 'pkg-1' };
+ state.item = state.items.packages[0];
+ });
+
+ it('shows on the Packages tab with what it holds', async () => {
+ state.params = { serverId: 'srv' };
+ await render(libraryView.MainPanel);
+ await act(async () => button('Packages')!.click());
+ await settle();
+ expect(cardFor('Onboarding').textContent).toContain('2 references · 1 document');
+ });
+
+ it('lists what it holds and adds more from the library', async () => {
+ await render(libraryItemView.MainPanel);
+ expect(container.querySelector('[aria-label="References"]')?.textContent).toContain(
+ 'Switch repo'
+ );
+ await act(async () => button('Add reference')!.click());
+ await settle();
+ const dialog = document.querySelector('[data-slot="dialog-content"]')!;
+ // Switch repo is already in it; Tracker is not.
+ expect(dialog.textContent).toContain('Tracker');
+ expect(dialog.textContent).not.toContain('Switch repo');
+ const add = [...dialog.querySelectorAll('button')].find((b) => b.textContent === 'Add')!;
+ await act(async () => add.click());
+ await settle();
+ expect(rpcMock.addPackageMember).toHaveBeenCalledWith({
+ workspaceId: 'ws',
+ packageId: 'pkg-1',
+ kind: 'references',
+ memberId: 'ref-2',
+ });
+ });
+
+ it('asks before removing, then says which rooms lost it', async () => {
+ await render(libraryItemView.MainPanel);
+ await act(async () =>
+ container
+ .querySelector<HTMLButtonElement>('[aria-label="Remove Switch repo from the package"]')!
+ .click()
+ );
+ expect(rpcMock.removePackageMember).not.toHaveBeenCalled();
+ expect(container.textContent).toContain(
+ 'Rooms that have it only through this package lose it.'
+ );
+ await act(async () => button('Remove')!.click());
+ await settle();
+ expect(rpcMock.removePackageMember).toHaveBeenCalledWith({
+ workspaceId: 'ws',
+ packageId: 'pkg-1',
+ kind: 'references',
+ memberId: 'ref-1',
+ });
+ expect(container.textContent).toContain('design, 1 private room you can’t open');
+ });
+
+ it('offers no adding or removing to someone who may not change it', async () => {
+ state.item = { ...(state.items.packages[0] as object), ownerId: 'bob' };
+ await render(libraryItemView.MainPanel);
+ expect(button('Add reference')).toBeUndefined();
+ expect(container.querySelector('[aria-label^="Remove "]')).toBeNull();
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-servers/library.ts b/console/apps/switch-console-desktop/src/shared/core/switch-servers/library.ts
index f0ad92575..91b2fbb3d 100644
--- a/console/apps/switch-console-desktop/src/shared/core/switch-servers/library.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/switch-servers/library.ts
@@ -1,11 +1,14 @@
/**
- * The workspace's library: references and documents anyone may attach to a
- * room, as the gateway's Resources pages show them. Packages bundle them and
- * join later.
+ * The workspace's library ("Resources" to people): references and documents
+ * anyone may attach to a room, and packages bundling them, as the gateway's
+ * Resources pages show them.
*/
-/** The library kinds the Library page lists. */
-export type LibraryKind = 'references' | 'documents';
+/** The library kinds the Resources page lists. */
+export type LibraryKind = 'references' | 'documents' | 'packages';
+
+/** What a package can hold. */
+export type PackageMemberKind = 'references' | 'documents';
/** Who may read, or change, a library item: its owner (and admins) alone, or everyone. */
export type LibraryVisibility = 'private' | 'public';
@@ -36,8 +39,11 @@ export type LibraryItem = {
* them; undefined from an older one.
*/
hiddenRoomsCount?: number;
- /** The packages it is in, by id. */
+ /** The packages it is in, by id; empty for a package. */
packageIds: string[];
+ /** What a package holds, by kind; zero for anything else. */
+ referencesCount: number;
+ documentsCount: number;
createdAt: string;
};
@@ -86,3 +92,13 @@ export type LibraryItemRoom = {
/** Whether the viewer may detach the item from this room, when the server says. */
canUnlink?: boolean;
};
+
+/**
+ * What taking something out of a package cost: the rooms that had it only
+ * through the package, by name where the viewer may read them, the rest
+ * counted (by a server that counts them).
+ */
+export type PackageMemberRemoval = {
+ affectedRoomNames: string[];
+ hiddenAffectedRoomsCount: number;
+};