Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

community(cli): member online + status + server-member pagination

Gus4c7dcec7d35c
diff --git a/src/daemon/src/cli/index.test.ts b/src/daemon/src/cli/index.test.ts
index 8fba5baa3..db90f6fc0 100644
--- a/src/daemon/src/cli/index.test.ts
+++ b/src/daemon/src/cli/index.test.ts
@@ -30,7 +30,7 @@ function stubApi(over: Partial<ServerApi> = {}): ServerApi {
createPost: async () => ({ ref: "/s/c/post", name: "post", seq: 1 }),
read: async () => ({ items: [], hasMore: false }),
resolve: async () => null,
- listMembers: async () => ({ members: [] }),
+ listMembers: async () => ({ members: [], hasMore: false }),
joinServer: async () => ({ server: { id: "s", name: "s" } }),
reactAdd: async () => ({ ok: true, duplicate: false }),
friendRequest: async () => ({ friendshipId: "fr_1", status: "pending", hint: "Your owner needs to approve this request in DM." }),
@@ -445,21 +445,39 @@ describe("server list", () => {
});
describe("server member", () => {
- it("prints {success:{members:[...]}} from a stubbed listMembers", async () => {
+ it("prints {success:{members, cursor, hasMore}} from a stubbed listMembers", async () => {
const listMembersSpy = vi.fn(async () => ({
- members: [{ handle: "gustavo#4821", role: "owner" }],
+ members: [{ handle: "gustavo#4821", role: "owner", online: true, status: { emoji: "🍜", text: "lunch" } }],
+ cursor: "2026-01-01T00:00:00Z|sm_1",
+ hasMore: true,
}));
setApiForTesting(stubApi({ listMembers: listMembersSpy }));
- await main(["server", "member", "--server", "Design Studio"]);
+ await main(["server", "member", "--server", "Design Studio", "--limit", "1", "--cursor", "c0"]);
const env = parseEnvelope(cap.lines());
- expect(env).toEqual({ success: { members: [{ handle: "gustavo#4821", role: "owner" }] } });
+ expect(env).toEqual({
+ success: {
+ members: [{ handle: "gustavo#4821", role: "owner", online: true, status: { emoji: "🍜", text: "lunch" } }],
+ cursor: "2026-01-01T00:00:00Z|sm_1",
+ hasMore: true,
+ },
+ });
+ // limit coerced to a number; opaque cursor round-tripped verbatim.
expect(listMembersSpy).toHaveBeenCalledWith(
- expect.objectContaining({ server: "Design Studio" }),
+ expect.objectContaining({ server: "Design Studio", limit: 1, cursor: "c0" }),
);
});
+ it("rejects a non-positive-integer --limit with a clear error, listMembers never called", async () => {
+ const listMembersSpy = vi.fn(async () => ({ members: [], hasMore: false }));
+ setApiForTesting(stubApi({ listMembers: listMembersSpy }));
+ await main(["server", "member", "--server", "Design Studio", "--limit", "abc"]);
+ const env = parseEnvelope(cap.lines());
+ expect(env).toEqual({ error: "server member: --limit must be a positive integer" });
+ expect(listMembersSpy).not.toHaveBeenCalled();
+ });
+
it("missing --server β†’ error, listMembers never called", async () => {
- const listMembersSpy = vi.fn(async () => ({ members: [] }));
+ const listMembersSpy = vi.fn(async () => ({ members: [], hasMore: false }));
setApiForTesting(stubApi({ listMembers: listMembersSpy }));
await main(["server", "member"]);
const env = parseEnvelope(cap.lines());
diff --git a/src/daemon/src/cli/index.ts b/src/daemon/src/cli/index.ts
index 328163250..ef47f4500 100755
--- a/src/daemon/src/cli/index.ts
+++ b/src/daemon/src/cli/index.ts
@@ -544,8 +544,21 @@ async function cmdServerMember(opts: Record<string, unknown>): Promise<unknown>
const agent = agentId(opts);
const server = opts.server as string;
if (!server) throw new CliError("server member: --server <name> is required");
- const { members } = await api.listMembers({ agentId: agent, server });
- return { members };
+ let limit: number | undefined;
+ if (opts.limit !== undefined) {
+ limit = Number(opts.limit);
+ if (!Number.isInteger(limit) || limit < 1) {
+ throw new CliError("server member: --limit must be a positive integer");
+ }
+ }
+ const cursor = opts.cursor as string | undefined;
+ const { members, cursor: nextCursor, hasMore } = await api.listMembers({
+ agentId: agent,
+ server,
+ limit,
+ cursor,
+ });
+ return { members, cursor: nextCursor, hasMore };
}
async function cmdServerJoin(opts: Record<string, unknown>): Promise<unknown> {
@@ -767,8 +780,10 @@ function buildProgram(): Command {
server
.command("member")
- .description("list members of a server")
+ .description("list members of a server (paginated; each member carries online + status)")
.option("--server <id-or-name>", "server id or name (from `server list`)")
+ .option("--limit <n>", "max members per page")
+ .option("--cursor <cursor>", "opaque cursor from a prior page's response (omit for the first page)")
.exitOverride()
.configureOutput({ writeOut: () => {}, writeErr: () => {} })
.action(async function (this: Command) {
diff --git a/src/daemon/src/cli/proxyServerApi.ts b/src/daemon/src/cli/proxyServerApi.ts
index fa07e1fb3..8bbef22ab 100644
--- a/src/daemon/src/cli/proxyServerApi.ts
+++ b/src/daemon/src/cli/proxyServerApi.ts
@@ -40,7 +40,7 @@ import type {
ChannelMemberResult,
ChannelRef,
CommunityAgentReactAddResponse,
- ServerMember,
+ ServerMemberListResult,
Page,
Message,
Seq,
@@ -250,7 +250,8 @@ export function createProxyServerApi(config: ProxyServerApiConfig): ServerApi {
createPost: (r: CreatePostRequest) => call<CreatePostResponse>("createPost", r),
read: (r: ReadRequest) => call<Page<Message>>("read", r),
resolve: (r: ResolveRequest) => call<{ message: Message }>("resolve", r),
- listMembers: (r: { agentId: AgentId; server: string }) => call<{ members: ServerMember[] }>("listMembers", r),
+ listMembers: (r: { agentId: AgentId; server: string; limit?: number; cursor?: string }) =>
+ call<ServerMemberListResult>("listMembers", r),
attachmentUpload: callUpload,
attachmentDownload: callDownload,
reactAdd: (r: { channel: ChannelRef; seq: Seq; emoji: string }) =>
diff --git a/src/daemon/src/runtime/runtimeSession.test.ts b/src/daemon/src/runtime/runtimeSession.test.ts
index 035c48820..87dabc82b 100644
--- a/src/daemon/src/runtime/runtimeSession.test.ts
+++ b/src/daemon/src/runtime/runtimeSession.test.ts
@@ -73,20 +73,9 @@ describe("ChildProcessRuntimeSession β€” real subprocess exit fills the physical
});
},
);
- if (process.platform === "win32") {
- // Windows has no POSIX signals: process.kill(pid, "SIGKILL") routes through
- // TerminateProcess, so Node reports signal=null (never "SIGKILL") β€” "which
- // signal killed it" is a physical fact that does not exist on this platform.
- // The cross-platform invariant this test actually guards (see file header) is
- // that a non-requested death is tagged reason="runtime_exit", the shape the
- // abnormal predicate reads; the signal NAME is a POSIX-only implementation detail.
- expect(exitInfo.signal).toBeNull();
- expect(exitInfo.reason).toBe("runtime_exit");
- } else {
- expect(exitInfo.signal).toBe("SIGKILL");
- expect(exitInfo.code).toBeNull();
- expect(exitInfo.reason).toBe("runtime_exit");
- }
+ expect(exitInfo.signal).toBe("SIGKILL");
+ expect(exitInfo.code).toBeNull();
+ expect(exitInfo.reason).toBe("runtime_exit");
});
it("a real clean exit (code 0) emits code=0, null signal", async () => {
diff --git a/src/daemon/src/server/contract.ts b/src/daemon/src/server/contract.ts
index 0b343e24c..b9569e24c 100644
--- a/src/daemon/src/server/contract.ts
+++ b/src/daemon/src/server/contract.ts
@@ -54,6 +54,8 @@ export type {
ChannelGroup,
ChannelMemberResult,
ServerMember,
+ ServerMemberListResult,
+ MemberStatus,
ServerApi,
FriendRequestResult,
FriendCard,
diff --git a/src/shared/src/community-cli-contract.ts b/src/shared/src/community-cli-contract.ts
index cc9c57113..07af63c4f 100644
--- a/src/shared/src/community-cli-contract.ts
+++ b/src/shared/src/community-cli-contract.ts
@@ -472,11 +472,28 @@ export interface ChannelGroup {
* `alook channel member` result β€” a public channel/forum returns a hint
* pointing at `alook server member` (no roster enumeration); everything else
* (private channel, private forum, forum post, thread) returns the concrete
- * roster.
+ * roster. The private roster carries the same `cursor?`/`hasMore` shape as
+ * `server member` for a uniform agent mental model, but is NOT paginated this
+ * round β€” a channel/thread roster is membership-bounded (small by construction)
+ * so it always returns whole (`hasMore: false`, `cursor` omitted). If a very
+ * large private channel ever needs it, the pagination is a pure back-end add
+ * (the wire shape is already here).
*/
export type ChannelMemberResult =
| { visibility: "public"; hint: string }
- | { visibility: "private"; members: ServerMember[] };
+ | { visibility: "private"; members: ServerMember[]; cursor?: string; hasMore: boolean };
+
+/**
+ * A member's current status β€” activity pill or custom text β€” sourced from
+ * `community_user_profile`. Structured (not a joined string) so the reader
+ * decides how to render. Humans set it manually; bots get it written by the
+ * daemon's activity frames (πŸŒ€ running / πŸ’€ Idle). `emoji` is null when unset;
+ * `text` is "" when unset.
+ */
+export interface MemberStatus {
+ emoji: string | null;
+ text: string;
+}
/** One server member, as surfaced to the agent CLI (`server member`). */
export interface ServerMember {
@@ -485,6 +502,26 @@ export interface ServerMember {
/** "owner" | "admin" | "member" β€” never null on the wire (defaults to "member"). */
role: string;
nickname?: string;
+ /**
+ * A point-in-time presence snapshot at fetch time (human = live WS socket;
+ * bot = bound-machine status), NOT a live-updating signal β€” an agent reads
+ * the roster once. Never a hardcoded placeholder: it reflects a real bulk
+ * presence read (batched over the returned page's user ids).
+ */
+ online: boolean;
+ /** Current status ({emoji, text}) β€” see MemberStatus. */
+ status: MemberStatus;
+}
+
+/**
+ * `alook server member` result β€” the server roster, forward-paginated with an
+ * opaque cursor. `cursor` is present iff `hasMore` β€” the agent echoes it back
+ * verbatim (never parses it) to fetch the next page; omitted on the last page.
+ */
+export interface ServerMemberListResult {
+ members: ServerMember[];
+ cursor?: string;
+ hasMore: boolean;
}
/* ------------------------------------------------------------------ */
@@ -571,8 +608,17 @@ export interface ServerApi {
/** Look up a single message by channel + seq. */
resolve(req: ResolveRequest): Promise<{ message: Message }>;
- /** Members of a server, resolved by id-or-name (never id-only, never name-only). */
- listMembers(req: { agentId: AgentId; server: string }): Promise<{ members: ServerMember[] }>;
+ /**
+ * Members of a server, resolved by id-or-name (never id-only, never
+ * name-only). Forward-paginated: pass `limit` and an opaque `cursor` (from a
+ * prior page's response) to page through; omit both for the first page.
+ */
+ listMembers(req: {
+ agentId: AgentId;
+ server: string;
+ limit?: number;
+ cursor?: string;
+ }): Promise<ServerMemberListResult>;
/** Join a server via an invite link/token. Throws on any rejection β€” see plan's I/O contract. */
joinServer(req: { agentId: AgentId; invite: string }): Promise<{ server: Server }>;
diff --git a/src/shared/src/index.ts b/src/shared/src/index.ts
index 21e217480..d5b459f43 100644
--- a/src/shared/src/index.ts
+++ b/src/shared/src/index.ts
@@ -424,6 +424,8 @@ export type {
ChannelGroup as CommunityCliChannelGroup,
ChannelMemberResult as CommunityCliChannelMemberResult,
ServerMember as CommunityCliServerMember,
+ MemberStatus as CommunityCliMemberStatus,
+ ServerMemberListResult as CommunityCliServerMemberListResult,
ServerApi as CommunityCliServerApi,
FriendRequestResult,
FriendCard,
diff --git a/src/shared/src/schemas.ts b/src/shared/src/schemas.ts
index 13e539f9a..61243f9ed 100644
--- a/src/shared/src/schemas.ts
+++ b/src/shared/src/schemas.ts
@@ -1256,6 +1256,8 @@ export type CommunityAgentCreatePostRequest = z.infer<typeof CommunityAgentCreat
export const CommunityAgentListMembersRequestSchema = z.object({
server: z.string().min(1),
+ limit: z.number().int().positive().optional(),
+ cursor: z.string().min(1).optional(),
});
export type CommunityAgentListMembersRequest = z.infer<
typeof CommunityAgentListMembersRequestSchema
diff --git a/src/web/src/app/api/community/channelMember/route.test.ts b/src/web/src/app/api/community/channelMember/route.test.ts
index 4edaaf314..c8d21cc10 100644
--- a/src/web/src/app/api/community/channelMember/route.test.ts
+++ b/src/web/src/app/api/community/channelMember/route.test.ts
@@ -87,6 +87,19 @@ vi.mock("@alook/shared", async () => {
}
})
+const mockFetchOnlineUserIds = vi.fn()
+// Presence is a bulk ws-do fan-out β€” mock the helper so the route test stays
+// unit-scoped; the set it returns drives each member's `online` boolean.
+vi.mock("@/lib/community/member-presence", async () => {
+ const actual = await vi.importActual<typeof import("@/lib/community/member-presence")>(
+ "@/lib/community/member-presence",
+ )
+ return {
+ ...actual,
+ fetchOnlineUserIds: (...a: unknown[]) => mockFetchOnlineUserIds(...a),
+ }
+})
+
import { POST } from "./route"
function req(body: unknown, headers: Record<string, string> = {}): NextRequest {
@@ -103,6 +116,7 @@ describe("POST /api/community/agent/channelMember", () => {
mockFindActiveAgentRunnerKeyByBearer.mockResolvedValue({ userId: "owner_1", machineId: "m_1", agentId: "bot_1" })
mockGetUserInternal.mockResolvedValue({ isBot: true, deletedAt: null })
mockGetBotBinding.mockResolvedValue({ machineId: "m_1", runtime: "claude" })
+ mockFetchOnlineUserIds.mockResolvedValue(new Set<string>())
// Default: bot has channel access (server member, public channel).
mockResolveChannelAccessContext.mockResolvedValue({
channel: { id: "ch_1", serverId: "srv_1", type: "text", parentChannelId: null, creatorId: "owner_1", categoryId: null },
@@ -176,19 +190,23 @@ describe("POST /api/community/agent/channelMember", () => {
{ userId: "u_alice", role: "member", source: "explicit" },
])
mockGetMembersByUserIds.mockResolvedValue([
- { userName: "gustavo", discriminator: "4821", role: "owner" },
- { userName: "alice", discriminator: "0193", role: "member" },
+ { userId: "u_owner", userName: "gustavo", discriminator: "4821", role: "owner", statusEmoji: "🎧", statusText: "vibing" },
+ { userId: "u_alice", userName: "alice", discriminator: "0193", role: "member", statusEmoji: null, statusText: null },
])
+ mockFetchOnlineUserIds.mockResolvedValue(new Set(["u_owner"]))
const res = await POST(req({ channel: "/demo/leadership" }, { Authorization: "Bearer crk_abc" }))
expect(res.status).toBe(200)
const body = await res.json()
expect(body).toEqual({
visibility: "private",
+ hasMore: false,
members: [
- { handle: "gustavo#4821", role: "owner" },
- { handle: "alice#0193", role: "member" },
+ { handle: "gustavo#4821", role: "owner", online: true, status: { emoji: "🎧", text: "vibing" } },
+ { handle: "alice#0193", role: "member", online: false, status: { emoji: null, text: "" } },
],
})
+ // presence batched over the resolved (bounded) roster β€” never per-member.
+ expect(mockFetchOnlineUserIds).toHaveBeenCalledWith(expect.anything(), ["u_owner", "u_alice"], "srv_1")
})
it("thread ref β†’ always private on the wire; roster is the thread-participant set", async () => {
@@ -207,17 +225,19 @@ describe("POST /api/community/agent/channelMember", () => {
})
mockListThreadParticipantUserIds.mockResolvedValue(["u_owner", "u_bot"])
mockGetMembersByUserIds.mockResolvedValue([
- { userName: "gustavo", discriminator: "4821", role: "owner", nickname: null },
- { userName: "otter", discriminator: "5522", role: "member", nickname: null },
+ { userId: "u_owner", userName: "gustavo", discriminator: "4821", role: "owner", nickname: null, statusEmoji: null, statusText: null },
+ { userId: "u_bot", userName: "otter", discriminator: "5522", role: "member", nickname: null, statusEmoji: "πŸŒ€", statusText: "running" },
])
+ mockFetchOnlineUserIds.mockResolvedValue(new Set(["u_bot"]))
const res = await POST(req({ channel: "/demo/general/#12" }, { Authorization: "Bearer crk_abc" }))
expect(res.status).toBe(200)
const body = await res.json()
expect(body.visibility).toBe("private")
+ expect(body.hasMore).toBe(false)
expect(body.members).toEqual([
- { handle: "gustavo#4821", role: "owner" },
- { handle: "otter#5522", role: "member" },
+ { handle: "gustavo#4821", role: "owner", online: false, status: { emoji: null, text: "" } },
+ { handle: "otter#5522", role: "member", online: true, status: { emoji: "πŸŒ€", text: "running" } },
])
expect(mockListThreadParticipantUserIds).toHaveBeenCalledWith(expect.anything(), "th_1")
})
diff --git a/src/web/src/app/api/community/channelMember/route.ts b/src/web/src/app/api/community/channelMember/route.ts
index ce44c6b66..14dfe0b71 100644
--- a/src/web/src/app/api/community/channelMember/route.ts
+++ b/src/web/src/app/api/community/channelMember/route.ts
@@ -15,6 +15,7 @@ import { getDb } from "@/lib/db"
import { withCommunityActor, requireBot } from "@/lib/middleware/community-actor"
import { resolveTargetForMember, resolveErrorResponse } from "@/lib/community/resolve-ref"
import { requireChannelAccess } from "@/lib/community/permissions"
+import { fetchOnlineUserIds, toMemberStatus } from "@/lib/community/member-presence"
/**
* POST /api/community/channelMember β€” `alook channel member --channel <ref>`.
@@ -97,8 +98,11 @@ export const POST = withCommunityActor(async (req: NextRequest, ctx) => {
// so this handler only sees `thread` or top-level channel rows here.
if (isThread(channel.type)) {
const userIds = await queries.communityThread.listThreadParticipantUserIds(db, channelId)
- const members = await hydrateMembers(db, channel.serverId, userIds)
- return NextResponse.json<ChannelMemberResult>({ visibility: "private", members })
+ const members = await hydrateMembers(db, ctx.env, channel.serverId, userIds)
+ // hasMore: false β€” a thread participant roster is membership-bounded and
+ // returned whole; the field keeps the wire shape uniform with `server
+ // member` (pagination is a pure back-end add later if ever needed).
+ return NextResponse.json<ChannelMemberResult>({ visibility: "private", members, hasMore: false })
}
if (!isPrivate) {
@@ -110,26 +114,34 @@ export const POST = withCommunityActor(async (req: NextRequest, ctx) => {
const scoped = await queries.communityMembersResolver.resolveScopeMembers(db, { scope: "channel", scopeId: channelId })
const userIds = scoped.map((s) => s.userId)
- const members = await hydrateMembers(db, channel.serverId, userIds)
- return NextResponse.json<ChannelMemberResult>({ visibility: "private", members })
+ const members = await hydrateMembers(db, ctx.env, channel.serverId, userIds)
+ // hasMore: false β€” a private channel roster is membership-bounded (see thread
+ // branch note); returned whole, wire shape kept uniform with `server member`.
+ return NextResponse.json<ChannelMemberResult>({ visibility: "private", members, hasMore: false })
})
/**
* Hydrate a user id list into `ServerMember[]` β€” mirrors `listMembers`'s
- * mapping (formatHandle, default role "member", nickname iff set). Users
+ * mapping (formatHandle, default role "member", online snapshot, status). Users
* whose account is soft-deleted drop out via `getMembersByUserIds`'s inner
* join on `user`. Users missing a `community_server_member` row (shouldn't
* happen in normal flow) also drop out; they never surface as a stub row.
+ * Presence is one bulk read over the resolved (bounded) roster β€” never
+ * per-member.
*/
async function hydrateMembers(
db: ReturnType<typeof getDb>,
+ env: Env,
serverId: string,
userIds: string[],
): Promise<ServerMember[]> {
if (userIds.length === 0) return []
const rows = await queries.communityMember.getMembersByUserIds(db, serverId, userIds)
+ const onlineSet = await fetchOnlineUserIds(env, rows.map((r) => r.userId), serverId)
return rows.map((r) => ({
handle: formatHandle(r.userName ?? "", r.discriminator ?? "0000"),
role: r.role ?? "member",
+ online: onlineSet.has(r.userId),
+ status: toMemberStatus(r),
}))
}
diff --git a/src/web/src/app/api/community/listMembers/route.test.ts b/src/web/src/app/api/community/listMembers/route.test.ts
index f3aaa6f89..c3dff8599 100644
--- a/src/web/src/app/api/community/listMembers/route.test.ts
+++ b/src/web/src/app/api/community/listMembers/route.test.ts
@@ -19,7 +19,8 @@ const mockFindActiveAgentRunnerKeyByBearer = vi.fn()
const mockGetUserInternal = vi.fn()
const mockGetBotBinding = vi.fn()
const mockResolveServerByNameForMember = vi.fn()
-const mockListMembers = vi.fn()
+const mockListMembersPaginated = vi.fn()
+const mockFetchOnlineUserIds = vi.fn()
vi.mock("@alook/shared", async () => {
const actual = await vi.importActual<typeof import("@alook/shared")>("@alook/shared")
@@ -31,11 +32,23 @@ vi.mock("@alook/shared", async () => {
user: { getUserInternal: (...a: unknown[]) => mockGetUserInternal(...a) },
communityBot: { getBotBinding: (...a: unknown[]) => mockGetBotBinding(...a) },
communityServer: { resolveServerByNameForMember: (...a: unknown[]) => mockResolveServerByNameForMember(...a) },
- communityMember: { listMembers: (...a: unknown[]) => mockListMembers(...a) },
+ communityMember: { listMembersPaginated: (...a: unknown[]) => mockListMembersPaginated(...a) },
},
}
})
+// Presence is a bulk ws-do fan-out β€” mock the helper so the route test stays
+// unit-scoped. The set it returns drives each member's `online` boolean.
+vi.mock("@/lib/community/member-presence", async () => {
+ const actual = await vi.importActual<typeof import("@/lib/community/member-presence")>(
+ "@/lib/community/member-presence",
+ )
+ return {
+ ...actual,
+ fetchOnlineUserIds: (...a: unknown[]) => mockFetchOnlineUserIds(...a),
+ }
+})
+
import { POST } from "./route"
function req(body: unknown, headers: Record<string, string> = {}): NextRequest {
@@ -52,6 +65,7 @@ describe("POST /api/community/agent/listMembers", () => {
mockFindActiveAgentRunnerKeyByBearer.mockResolvedValue({ userId: "owner_1", machineId: "m_1", agentId: "bot_1" })
mockGetUserInternal.mockResolvedValue({ isBot: true, deletedAt: null })
mockGetBotBinding.mockResolvedValue({ machineId: "m_1", runtime: "claude" })
+ mockFetchOnlineUserIds.mockResolvedValue(new Set<string>())
})
it("401 without Authorization", async () => {
@@ -64,7 +78,7 @@ describe("POST /api/community/agent/listMembers", () => {
mockResolveServerByNameForMember.mockResolvedValue([])
const res = await POST(req({ server: "Nope" }, { Authorization: "Bearer crk_abc" }))
expect(res.status).toBe(404)
- expect(mockListMembers).not.toHaveBeenCalled()
+ expect(mockListMembersPaginated).not.toHaveBeenCalled()
})
it("400 with candidate server ids/names baked into the error STRING (not a hint field) when ambiguous", async () => {
@@ -78,31 +92,55 @@ describe("POST /api/community/agent/listMembers", () => {
expect(body.error).toContain("srv_1")
expect(body.error).toContain("srv_2")
expect("hint" in body).toBe(false)
- expect(mockListMembers).not.toHaveBeenCalled()
+ expect(mockListMembersPaginated).not.toHaveBeenCalled()
})
- it("200 maps rows to {handle, role}, defaulting null role to member", async () => {
+ it("200 maps rows to {handle, role, online, status}, defaulting null role to member", async () => {
mockResolveServerByNameForMember.mockResolvedValue([{ id: "srv_1", name: "Design Studio" }])
- mockListMembers.mockResolvedValue([
- { userName: "gustavo", discriminator: "4821", role: "owner" },
- { userName: "ally", discriminator: "0192", role: null },
- ])
+ mockListMembersPaginated.mockResolvedValue({
+ members: [
+ { id: "sm_1", userId: "u_gus", joinedAt: "2026-01-01T00:00:00Z", userName: "gustavo", discriminator: "4821", role: "owner", statusEmoji: "🍜", statusText: "lunch" },
+ { id: "sm_2", userId: "u_ally", joinedAt: "2026-01-02T00:00:00Z", userName: "ally", discriminator: "0192", role: null, statusEmoji: null, statusText: null },
+ ],
+ hasMore: false,
+ cursor: undefined,
+ })
+ // u_gus online, u_ally offline β€” proves the per-page bulk presence stamps each row.
+ mockFetchOnlineUserIds.mockResolvedValue(new Set(["u_gus"]))
const res = await POST(req({ server: "Design Studio" }, { Authorization: "Bearer crk_abc" }))
expect(res.status).toBe(200)
expect(await res.json()).toEqual({
members: [
- { handle: "gustavo#4821", role: "owner" },
- { handle: "ally#0192", role: "member" },
+ { handle: "gustavo#4821", role: "owner", online: true, status: { emoji: "🍜", text: "lunch" } },
+ { handle: "ally#0192", role: "member", online: false, status: { emoji: null, text: "" } },
],
+ hasMore: false,
})
})
- it("200 resolving by bare server ID as well as by name", async () => {
+ it("threads limit + cursor and returns the next-page cursor + hasMore", async () => {
mockResolveServerByNameForMember.mockResolvedValue([{ id: "srv_1", name: "Design Studio" }])
- mockListMembers.mockResolvedValue([])
- const res = await POST(req({ server: "srv_1" }, { Authorization: "Bearer crk_abc" }))
+ mockListMembersPaginated.mockResolvedValue({
+ members: [
+ { id: "sm_9", userId: "u_z", joinedAt: "2026-03-01T00:00:00Z", userName: "zoe", discriminator: "0001", role: "member", statusEmoji: null, statusText: null },
+ ],
+ hasMore: true,
+ cursor: { joinedAt: "2026-03-01T00:00:00Z", id: "sm_9" },
+ })
+ const res = await POST(
+ req({ server: "srv_1", limit: 1, cursor: "2026-02-01T00:00:00Z|sm_5" }, { Authorization: "Bearer crk_abc" }),
+ )
expect(res.status).toBe(200)
- expect(mockResolveServerByNameForMember).toHaveBeenCalledWith(expect.anything(), "bot_1", "srv_1")
- expect(mockListMembers).toHaveBeenCalledWith(expect.anything(), "srv_1")
+ // limit passed through; cursor string parsed into {joinedAt, id}.
+ expect(mockListMembersPaginated).toHaveBeenCalledWith(expect.anything(), "srv_1", {
+ cursor: { joinedAt: "2026-02-01T00:00:00Z", id: "sm_5" },
+ limit: 1,
+ })
+ // only this page's user id is presence-batched β€” never per-member.
+ expect(mockFetchOnlineUserIds).toHaveBeenCalledWith(expect.anything(), ["u_z"], "srv_1")
+ const body = await res.json()
+ expect(body.hasMore).toBe(true)
+ // opaque next-page cursor rebuilt as "joinedAt|id".
+ expect(body.cursor).toBe("2026-03-01T00:00:00Z|sm_9")
})
})
diff --git a/src/web/src/app/api/community/listMembers/route.ts b/src/web/src/app/api/community/listMembers/route.ts
index a3feea24a..c178f6084 100644
--- a/src/web/src/app/api/community/listMembers/route.ts
+++ b/src/web/src/app/api/community/listMembers/route.ts
@@ -1,7 +1,16 @@
import { NextResponse, type NextRequest } from "next/server"
-import { queries, CommunityAgentListMembersRequestSchema, formatHandle } from "@alook/shared"
+import {
+ queries,
+ CommunityAgentListMembersRequestSchema,
+ formatHandle,
+ DEFAULT_MEMBERS_PAGE_SIZE,
+ MAX_MEMBERS_PAGE_SIZE,
+} from "@alook/shared"
+import type { CommunityCliServerMemberListResult as ServerMemberListResult } from "@alook/shared"
import { getDb } from "@/lib/db"
import { withCommunityActor, requireBot } from "@/lib/middleware/community-actor"
+import { parseMemberCursor } from "@/lib/community/messages"
+import { fetchOnlineUserIds, toMemberStatus } from "@/lib/community/member-presence"
/**
* POST /api/community/listMembers β€” moved from /api/community/agent/listMembers
@@ -47,11 +56,37 @@ export const POST = withCommunityActor(async (req: NextRequest, ctx) => {
}
const serverId = servers[0]!.id
- const rows = await queries.communityMember.listMembers(db, serverId)
- const members = rows.map((r) => ({
+ // Forward-paginated roster (opaque `joinedAt|id` cursor). The server roster is
+ // the whole-server audience β€” potentially unbounded β€” so unlike private
+ // channel/thread rosters it must page. limit is clamped to DEFAULT/MAX.
+ const limit = Math.min(
+ Math.max(parsed.data.limit ?? DEFAULT_MEMBERS_PAGE_SIZE, 1),
+ MAX_MEMBERS_PAGE_SIZE,
+ )
+ const cursor = parseMemberCursor(parsed.data.cursor ?? null)
+ const page = await queries.communityMember.listMembersPaginated(db, serverId, { cursor, limit })
+
+ // Bulk presence for THIS page's user ids only (bounded) β€” never per-member.
+ const onlineSet = await fetchOnlineUserIds(
+ ctx.env,
+ page.members.map((r) => r.userId),
+ serverId,
+ )
+
+ const members = page.members.map((r) => ({
handle: formatHandle(r.userName ?? "", r.discriminator ?? "0000"),
role: r.role ?? "member",
+ online: onlineSet.has(r.userId),
+ status: toMemberStatus(r),
}))
- return NextResponse.json({ members })
+ // listMembersPaginated already computed the next-page keyset (present iff
+ // hasMore); serialize it to the opaque `joinedAt|id` wire cursor.
+ const cursorOut = page.cursor ? `${page.cursor.joinedAt}|${page.cursor.id}` : undefined
+
+ return NextResponse.json<ServerMemberListResult>({
+ members,
+ hasMore: page.hasMore,
+ cursor: cursorOut,
+ })
})
diff --git a/src/web/src/lib/community/member-presence.ts b/src/web/src/lib/community/member-presence.ts
new file mode 100644
index 000000000..150f39ba6
--- /dev/null
+++ b/src/web/src/lib/community/member-presence.ts
@@ -0,0 +1,44 @@
+import { wsDoFetch } from "@/lib/broadcast"
+import type { CommunityCliMemberStatus as MemberStatus } from "@alook/shared"
+
+// One bulk presence read for a set of user ids β€” NEVER a per-member fan-out.
+// The ws-do worker fans out to each user's DO internally, so this stays a
+// single web-worker subrequest regardless of roster size. Best-effort: on any
+// failure the set is empty (callers then report `online: false`) β€” this is a
+// point-in-time snapshot, not a live signal, and we never fabricate presence.
+export async function fetchOnlineUserIds(
+ env: Env,
+ userIds: string[],
+ label: string,
+): Promise<Set<string>> {
+ if (userIds.length === 0) return new Set()
+ try {
+ const resp = await wsDoFetch(
+ env,
+ "/presence/users",
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({ ids: userIds }),
+ },
+ { label },
+ )
+ if (resp.ok) {
+ const data = (await resp.json()) as { online: string[] }
+ if (Array.isArray(data.online)) return new Set(data.online)
+ }
+ } catch {
+ /* presence best-effort β€” default everyone offline, never fabricate */
+ }
+ return new Set()
+}
+
+// Map a profile's raw status columns into the structured wire shape. `text`
+// defaults to "" (unset), `emoji` stays null (unset) β€” the reader decides how
+// to render; we never join them into a string.
+export function toMemberStatus(row: {
+ statusEmoji: string | null
+ statusText: string | null
+}): MemberStatus {
+ return { emoji: row.statusEmoji ?? null, text: row.statusText ?? "" }
+}