@prjct.app/pi-team 0.6.1 → 0.7.0

package/src/process-identity.ts

@@ -0,0 +1,68 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+
+export type ProcessIdentity = Readonly<{
+  processPid: number;
+  processStartToken: string;
+  processGroupId: number;
+}>;
+
+export type ProcessController = Readonly<{
+  inspect(processPid: number): Promise<ProcessIdentity | undefined>;
+  signal(identity: ProcessIdentity, signal: NodeJS.Signals): Promise<boolean>;
+  delay(ms: number): Promise<void>;
+}>;
+
+function ps(args: readonly string[]): Promise<string> {
+  return new Promise((resolvePromise, reject) => {
+    execFile('ps', [...args], { env: process.env, timeout: 2_000 }, (error, stdout) => {
+      if (error) { reject(error); return; }
+      resolvePromise(String(stdout).trim());
+    });
+  });
+}
+
+async function inspectLinuxProcess(processPid: number): Promise<ProcessIdentity | undefined> {
+  const stat = await readFile(`/proc/${processPid}/stat`, 'utf8').catch(() => '');
+  const commandEnd = stat.lastIndexOf(') ');
+  const fields = commandEnd >= 0 ? stat.slice(commandEnd + 2).trim().split(/\s+/) : [];
+  const processGroupId = Number(fields[2]);
+  const startedAtClockTick = fields[19] ?? '';
+  if (!Number.isSafeInteger(processGroupId) || processGroupId <= 1 || !/^\d+$/.test(startedAtClockTick)) return undefined;
+  return { processPid, processGroupId, processStartToken: `linux:${startedAtClockTick}` };
+}
+
+async function inspectPortableProcess(processPid: number): Promise<ProcessIdentity | undefined> {
+  const output = await ps(['-o', 'pgid=', '-o', 'lstart=', '-p', String(processPid)]).catch(() => '');
+  const match = output.match(/^(\d+)\s+(.+)$/);
+  if (!match) return undefined;
+  const processGroupId = Number(match[1]);
+  const processStartToken = match[2]?.trim() ?? '';
+  if (!Number.isSafeInteger(processGroupId) || processGroupId <= 1 || !processStartToken) return undefined;
+  return { processPid, processStartToken: `ps:${processStartToken}`, processGroupId };
+}
+
+export async function inspectProcess(processPid: number): Promise<ProcessIdentity | undefined> {
+  if (!Number.isSafeInteger(processPid) || processPid <= 1) return undefined;
+  return process.platform === 'linux' ? inspectLinuxProcess(processPid) : inspectPortableProcess(processPid);
+}
+
+export function sameProcess(left: ProcessIdentity, right: ProcessIdentity | undefined): boolean {
+  return !!right && left.processPid === right.processPid && left.processStartToken === right.processStartToken &&
+    left.processGroupId === right.processGroupId;
+}
+
+async function signal(identity: ProcessIdentity, value: NodeJS.Signals): Promise<boolean> {
+  if (!sameProcess(identity, await inspectProcess(identity.processPid))) return false;
+  try { process.kill(-identity.processGroupId, value); return true; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+    throw error;
+  }
+}
+
+export const defaultProcessController: ProcessController = {
+  inspect: inspectProcess,
+  signal,
+  delay: ms => new Promise(resolve => setTimeout(resolve, ms)),
+};

package/src/runtime/delivery.ts

@@ -0,0 +1,326 @@
+import { createHash } from 'node:crypto';
+import { leaseExpired, type Lease } from '../domain/lease.ts';
+import { messageExpired, type Envelope, type ReceiptStatus } from '../domain/message.ts';
+import { withStorageLock } from '../storage/atomic.ts';
+import { InboxStore } from '../storage/inbox-store.ts';
+import { LeaseStore } from '../storage/lease-store.ts';
+import { ReceiptStore } from '../storage/receipt-store.ts';
+import { MembershipService, type Membership } from './membership.ts';
+
+export const DEFAULT_DELIVERY_LEASE_MS = 30_000;
+const terminalReceipts = new Set<ReceiptStatus>(['replied', 'cancelled', 'expired', 'failed']);
+
+export type DeliveryClaim = {
+  readonly teamId: string;
+  readonly memberId: string;
+  readonly memberGeneration: number;
+  readonly messageId: string;
+  readonly token: string;
+  readonly generation: number;
+};
+
+export type InboxItem = {
+  readonly messageId: string;
+  readonly threadId: string;
+  readonly requestId?: string;
+  readonly kind: Envelope['kind'];
+  readonly fromMemberId: string;
+  readonly createdAt: string;
+  readonly expiresAt: string;
+};
+
+export type ReconciledClaim = 'active' | 'released' | 'settled' | 'failed' | 'expired' | 'missing';
+
+export class DeliveryService {
+  private readonly leaseMs: number;
+  private readonly now: () => number;
+
+  constructor(
+    private readonly memberships: MembershipService,
+    private readonly inbox: InboxStore,
+    private readonly receipts: ReceiptStore,
+    private readonly leases: LeaseStore,
+    options: { readonly leaseMs?: number; readonly now?: () => number } = {},
+  ) {
+    this.leaseMs = options.leaseMs ?? DEFAULT_DELIVERY_LEASE_MS;
+    this.now = options.now ?? Date.now;
+    if (!Number.isFinite(this.leaseMs) || this.leaseMs <= 0) throw new Error('Invalid delivery lease duration.');
+  }
+
+  leaseId(messageId: string): string {
+    return `delivery-${createHash('sha256').update(messageId).digest('hex')}`;
+  }
+  holderId(membership: Membership): string {
+    return `member-${createHash('sha256').update(`${membership.memberId}:${membership.memberGeneration}`).digest('hex')}`;
+  }
+  private lockPath(teamId: string, messageId: string): string {
+    return this.leases.paths.lock(`delivery-op-${createHash('sha256').update(`${teamId}\0${messageId}`).digest('hex')}`);
+  }
+
+  private claimFromLease(membership: Membership, messageId: string, lease: Lease): DeliveryClaim {
+    return {
+      teamId: membership.teamId,
+      memberId: membership.memberId,
+      memberGeneration: membership.memberGeneration,
+      messageId,
+      token: lease.token,
+      generation: lease.generation,
+    };
+  }
+
+  private async ownedLease(membership: Membership, messageId: string): Promise<Lease> {
+    await this.memberships.assertOwner(membership);
+    const lease = await this.leases.read(membership.teamId, this.leaseId(messageId));
+    if (!lease || lease.kind !== 'delivery' || lease.resourceId !== messageId ||
+        lease.holderId !== this.holderId(membership) || leaseExpired(lease, this.now())) {
+      throw Object.assign(new Error('Delivery claim ownership has been fenced.'), { code: 'FENCED' });
+    }
+    return lease;
+  }
+
+  private async claimed(membership: Membership, messageId: string): Promise<Envelope> {
+    const message = await this.inbox.readClaimed(membership.teamId, membership.memberId, messageId);
+    if (!message) throw Object.assign(new Error(`Unknown claimed message "${messageId}".`), { code: 'NOT_FOUND' });
+    return message;
+  }
+
+  private async releaseLease(membership: Membership, messageId: string, lease: Lease): Promise<void> {
+    await this.leases.release(
+      membership.teamId, this.leaseId(messageId), this.holderId(membership), lease.token, lease.generation,
+    );
+  }
+
+  private async finishUnlocked(membership: Membership, messageId: string, lease: Lease): Promise<void> {
+    await this.inbox.removeClaimed(membership.teamId, membership.memberId, messageId);
+    await this.releaseLease(membership, messageId, lease).catch(() => {});
+  }
+
+  async inboxItems(membership: Membership, limit = 50, cursor?: string): Promise<{
+    readonly items: readonly InboxItem[];
+    readonly nextCursor?: string;
+  }> {
+    await this.memberships.assertOwner(membership);
+    const page = await this.inbox.listPending(membership.teamId, membership.memberId, limit, cursor);
+    return {
+      items: page.messages.map(({ body: _body, senderGeneration: _sender, recipientGeneration: _recipient, teamId: _team, schemaVersion: _schema, toMemberId: _to, ...item }) => item),
+      ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+    };
+  }
+
+  async claim(membership: Membership, messageId: string, signal?: AbortSignal): Promise<DeliveryClaim> {
+    return withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      signal?.throwIfAborted();
+      await this.memberships.assertOwner(membership);
+      const message = await this.inbox.readPending(membership.teamId, membership.memberId, messageId);
+      if (!message) throw Object.assign(new Error(`Unknown pending message "${messageId}".`), { code: 'NOT_FOUND' });
+      const receipt = await this.receipts.read(membership.teamId, membership.memberId, messageId);
+      if (receipt && terminalReceipts.has(receipt.status)) {
+        await this.inbox.removePending(membership.teamId, membership.memberId, messageId);
+        throw Object.assign(new Error(`Message is already ${receipt.status}.`), { code: 'TERMINAL_MESSAGE' });
+      }
+      const sender = await this.memberships.member(message.teamId, message.fromMemberId);
+      const recipientFenced = message.recipientGeneration !== undefined &&
+        message.recipientGeneration !== membership.memberGeneration;
+      const senderFenced = message.kind !== 'cancel' &&
+        (!sender || sender.generation !== message.senderGeneration ||
+          (message.kind === 'request' && sender.state !== 'active'));
+      if (recipientFenced || senderFenced) {
+        await this.receipts.record({
+          schemaVersion: 2,
+          teamId: membership.teamId,
+          messageId,
+          recipientId: membership.memberId,
+          status: 'failed',
+          at: new Date(this.now()).toISOString(),
+        });
+        await this.inbox.removePending(membership.teamId, membership.memberId, messageId);
+        throw Object.assign(new Error('Message ownership generation has been fenced.'), { code: 'FENCED' });
+      }
+      signal?.throwIfAborted();
+      const lease = await this.leases.acquire({
+        teamId: membership.teamId,
+        leaseId: this.leaseId(messageId),
+        kind: 'delivery',
+        holderId: this.holderId(membership),
+        resourceId: messageId,
+        ttlMs: this.leaseMs,
+      });
+      try {
+        signal?.throwIfAborted();
+        await this.inbox.claim(membership.teamId, membership.memberId, messageId);
+        return this.claimFromLease(membership, messageId, lease);
+      } catch (error) {
+        await this.releaseLease(membership, messageId, lease).catch(() => {});
+        throw error;
+      }
+    });
+  }
+
+  async read(membership: Membership, messageId: string, signal?: AbortSignal): Promise<Envelope> {
+    return withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      signal?.throwIfAborted();
+      const lease = await this.ownedLease(membership, messageId);
+      const message = await this.claimed(membership, messageId);
+      const receipt = await this.receipts.read(membership.teamId, membership.memberId, messageId);
+      if (messageExpired(message, this.now())) {
+        if (!receipt) {
+          await this.receipts.record({
+            schemaVersion: 2,
+            teamId: membership.teamId,
+            messageId,
+            recipientId: membership.memberId,
+            status: 'expired',
+            at: new Date(this.now()).toISOString(),
+          });
+        } else if (!terminalReceipts.has(receipt.status)) {
+          await this.receipts.record({ ...receipt, status: 'expired', at: new Date(this.now()).toISOString() });
+        }
+        await this.finishUnlocked(membership, messageId, lease);
+        throw Object.assign(new Error('Message has expired.'), { code: 'EXPIRED' });
+      }
+      if (receipt && terminalReceipts.has(receipt.status)) {
+        throw Object.assign(new Error(`Message is already ${receipt.status}.`), { code: 'TERMINAL_MESSAGE' });
+      }
+      if (message.kind === 'reply' && message.requestId) {
+        const original = await this.receipts.read(membership.teamId, message.fromMemberId, message.requestId);
+        if (!original || !terminalReceipts.has(original.status)) {
+          throw Object.assign(new Error('Reply outcome is not durable yet.'), { code: 'NOT_READY' });
+        }
+      }
+      signal?.throwIfAborted();
+      const timestamp = new Date(this.now()).toISOString();
+      if (!receipt) {
+        await this.receipts.record({
+          schemaVersion: 2,
+          teamId: membership.teamId,
+          messageId,
+          recipientId: membership.memberId,
+          status: 'delivered',
+          at: timestamp,
+        });
+      }
+      const delivered = receipt ?? await this.receipts.read(membership.teamId, membership.memberId, messageId);
+      if (delivered?.status === 'delivered') {
+        await this.receipts.record({ ...delivered, status: 'read', at: timestamp });
+      }
+      return message;
+    });
+  }
+
+  async renew(membership: Membership, messageId: string): Promise<DeliveryClaim> {
+    return withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      const lease = await this.ownedLease(membership, messageId);
+      const renewed = await this.leases.renew(
+        membership.teamId,
+        lease.leaseId,
+        this.holderId(membership),
+        lease.token,
+        lease.generation,
+        this.leaseMs,
+      );
+      return this.claimFromLease(membership, messageId, renewed);
+    });
+  }
+
+  async release(membership: Membership, messageId: string): Promise<void> {
+    await withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      const lease = await this.ownedLease(membership, messageId);
+      const receipt = await this.receipts.read(membership.teamId, membership.memberId, messageId);
+      if (receipt) throw new Error('A delivered message cannot be released for reinjection.');
+      await this.inbox.release(membership.teamId, membership.memberId, messageId);
+      await this.releaseLease(membership, messageId, lease);
+    });
+  }
+
+  async finish(membership: Membership, messageId: string): Promise<void> {
+    await withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      const lease = await this.ownedLease(membership, messageId);
+      await this.finishUnlocked(membership, messageId, lease);
+    });
+  }
+
+  async settle<T>(
+    membership: Membership,
+    messageId: string,
+    operation: (message: Envelope) => Promise<T>,
+  ): Promise<T> {
+    return withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      const lease = await this.ownedLease(membership, messageId);
+      const message = await this.claimed(membership, messageId);
+      const result = await operation(message);
+      await this.finishUnlocked(membership, messageId, lease);
+      return result;
+    });
+  }
+
+  async fail(membership: Membership, messageId: string): Promise<void> {
+    await withStorageLock(this.lockPath(membership.teamId, messageId), async () => {
+      const lease = await this.ownedLease(membership, messageId);
+      const receipt = await this.receipts.read(membership.teamId, membership.memberId, messageId);
+      if (receipt && !terminalReceipts.has(receipt.status)) {
+        await this.receipts.record({ ...receipt, status: 'failed', at: new Date(this.now()).toISOString() });
+      }
+      await this.finishUnlocked(membership, messageId, lease);
+    });
+  }
+
+  async reconcileClaim(teamId: string, recipientId: string, messageId: string): Promise<ReconciledClaim> {
+    return withStorageLock(this.lockPath(teamId, messageId), async () => {
+      const message = await this.inbox.readClaimed(teamId, recipientId, messageId);
+      if (!message) return 'missing';
+      const lease = await this.leases.read(teamId, this.leaseId(messageId));
+      const receipt = await this.receipts.read(teamId, recipientId, messageId);
+      const expired = messageExpired(message, this.now());
+      if (!expired && lease && !leaseExpired(lease, this.now()) &&
+          (!receipt || !terminalReceipts.has(receipt.status))) return 'active';
+      if (expired) {
+        if (!receipt) {
+          await this.receipts.record({
+            schemaVersion: 2,
+            teamId,
+            messageId,
+            recipientId,
+            status: 'expired',
+            at: new Date(this.now()).toISOString(),
+          });
+        } else if (!terminalReceipts.has(receipt.status)) {
+          await this.receipts.record({ ...receipt, status: 'expired', at: new Date(this.now()).toISOString() });
+        }
+        await this.inbox.removeClaimed(teamId, recipientId, messageId);
+        if (lease) await this.leases.release(teamId, lease.leaseId, lease.holderId, lease.token, lease.generation).catch(() => {});
+        return 'expired';
+      }
+      if (receipt) {
+        const terminal = terminalReceipts.has(receipt.status);
+        if (!terminal) {
+          await this.receipts.record({ ...receipt, status: 'failed', at: new Date(this.now()).toISOString() });
+        }
+        await this.inbox.removeClaimed(teamId, recipientId, messageId);
+        if (lease) await this.leases.release(teamId, lease.leaseId, lease.holderId, lease.token, lease.generation).catch(() => {});
+        return terminal ? 'settled' : 'failed';
+      }
+      await this.inbox.release(teamId, recipientId, messageId);
+      return 'released';
+    });
+  }
+
+  async deliverNextRequest(
+    membership: Membership,
+    humanEnabled: boolean,
+    inject: (message: Envelope) => Promise<void>,
+  ): Promise<Envelope | undefined> {
+    if (!humanEnabled || membership.kind !== 'supervised') return undefined;
+    const page = await this.inbox.listPending(membership.teamId, membership.memberId, 100);
+    const message = page.messages.find(candidate => candidate.kind === 'request');
+    if (!message) return undefined;
+    await this.claim(membership, message.messageId);
+    const delivered = await this.read(membership, message.messageId);
+    try {
+      await inject(delivered);
+      return delivered;
+    } catch (error) {
+      await this.fail(membership, message.messageId);
+      throw error;
+    }
+  }
+}

package/src/runtime/membership.ts

@@ -0,0 +1,212 @@
+import { randomUUID } from 'node:crypto';
+import type { Member, MemberKind } from '../domain/member.ts';
+import { assertEntityId, assertTeamId } from '../domain/team.ts';
+import { withStorageLock } from '../storage/atomic.ts';
+import { TeamPaths } from '../storage/paths.ts';
+import { TeamStore } from '../storage/team-store.ts';
+import { PresenceService, type PresenceOwner } from './presence.ts';
+
+export type Membership = PresenceOwner & {
+  readonly alias: string;
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly kind: MemberKind;
+};
+
+export type PeerStatus = {
+  readonly memberId: string;
+  readonly alias: string;
+  readonly kind: MemberKind;
+  readonly generation: number;
+  readonly status: 'online' | 'offline';
+};
+
+export type PeerPage = {
+  readonly peers: readonly PeerStatus[];
+  readonly nextCursor?: string;
+};
+
+function positiveInteger(value: string | undefined, label: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1) throw new Error(`Invalid ${label} in supervised Team environment.`);
+  return parsed;
+}
+
+export function workerMembershipFromEnvironment(
+  environment: NodeJS.ProcessEnv = process.env,
+  cwd = process.cwd(),
+): Membership | undefined {
+  const names = [
+    'PI_TEAM_TEAM_ID', 'PI_TEAM_MEMBER_ID', 'PI_TEAM_MEMBER_ALIAS', 'PI_TEAM_MEMBER_SESSION',
+    'PI_TEAM_MEMBER_GENERATION', 'PI_TEAM_MEMBER_LEASE_TOKEN', 'PI_TEAM_MEMBER_LEASE_GENERATION',
+  ] as const;
+  const present = names.filter(name => environment[name] !== undefined);
+  if (present.length === 0) return undefined;
+  if (present.length !== names.length) throw new Error('Incomplete supervised Team membership environment.');
+  const teamId = assertTeamId(environment.PI_TEAM_TEAM_ID!);
+  const memberId = assertEntityId(environment.PI_TEAM_MEMBER_ID!, 'member ID');
+  const alias = assertTeamId(environment.PI_TEAM_MEMBER_ALIAS!);
+  const sessionId = assertEntityId(environment.PI_TEAM_MEMBER_SESSION!, 'session ID');
+  const leaseToken = environment.PI_TEAM_MEMBER_LEASE_TOKEN!;
+  // Same shape the lease store issues and the lease schema accepts (a UUID
+  // today). Requiring 64 hex characters rejected every real Expert at startup.
+  if (!/^[A-Za-z0-9_-]{32,256}$/.test(leaseToken)) throw new Error('Invalid supervised Team membership environment.');
+  return {
+    teamId,
+    memberId,
+    memberGeneration: positiveInteger(environment.PI_TEAM_MEMBER_GENERATION, 'member generation'),
+    leaseToken,
+    leaseGeneration: positiveInteger(environment.PI_TEAM_MEMBER_LEASE_GENERATION, 'lease generation'),
+    alias,
+    sessionId,
+    cwd,
+    kind: 'supervised',
+  };
+}
+
+export class MembershipService {
+  constructor(
+    private readonly paths: TeamPaths,
+    private readonly teams: TeamStore,
+    private readonly presence: PresenceService,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  private lockPath(teamId: string): string { return this.paths.lock(`membership-${assertTeamId(teamId)}`); }
+
+  private membership(member: Member, owner: PresenceOwner): Membership {
+    if (!member.sessionId) throw new Error('Joined member is missing its session identity.');
+    return {
+      ...owner,
+      alias: member.alias,
+      sessionId: member.sessionId,
+      cwd: member.cwd,
+      kind: member.kind,
+    };
+  }
+
+  async join(input: {
+    readonly teamId: string;
+    readonly alias: string;
+    readonly sessionId: string;
+    readonly cwd: string;
+    readonly kind: MemberKind;
+  }): Promise<Membership> {
+    return withStorageLock(this.lockPath(input.teamId), async () => {
+      const team = await this.teams.read(input.teamId);
+      if (!team) throw Object.assign(new Error(`Unknown team "${input.teamId}".`), { code: 'NOT_FOUND' });
+      if (team.state !== 'open') throw Object.assign(new Error(`Team "${input.teamId}" is ${team.state}.`), { code: 'TEAM_CLOSED' });
+      const matching = (await this.teams.listMembers(input.teamId)).filter(member => member.alias === input.alias);
+      const active = matching.find(member => member.state === 'active');
+      if (active && await this.presence.online(active)) {
+        throw Object.assign(new Error(`Alias "${input.alias}" is already active.`), { code: 'ALREADY_EXISTS' });
+      }
+      const previous = active ?? [...matching].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+      const memberId = previous?.memberId ?? randomUUID();
+      const generation = (previous?.generation ?? 0) + 1;
+      const owner = await this.presence.acquire(input.teamId, memberId, generation);
+      const timestamp = new Date(this.now()).toISOString();
+      try {
+        if (!previous) {
+          const member: Member = {
+            schemaVersion: 2,
+            teamId: input.teamId,
+            memberId,
+            sessionId: input.sessionId,
+            alias: input.alias,
+            kind: input.kind,
+            generation,
+            state: 'active',
+            cwd: input.cwd,
+            joinedAt: timestamp,
+            updatedAt: timestamp,
+          };
+          await this.teams.createMember(member);
+          return this.membership(member, owner);
+        }
+        const member = await this.teams.updateMember(input.teamId, memberId, previous.generation, current => {
+          const { leftAt: _leftAt, ...retained } = current;
+          return {
+            ...retained,
+            sessionId: input.sessionId,
+            alias: input.alias,
+            kind: input.kind,
+            generation,
+            state: 'active',
+            cwd: input.cwd,
+            updatedAt: timestamp,
+          };
+        });
+        return this.membership(member, owner);
+      } catch (error) {
+        await this.presence.release(owner).catch(() => {});
+        throw error;
+      }
+    });
+  }
+
+  async assertOwner(membership: Membership): Promise<Member> {
+    const { member } = await this.presence.assertOwner(membership);
+    if (member.sessionId !== membership.sessionId || member.alias !== membership.alias) {
+      throw Object.assign(new Error('Membership identity has been replaced.'), { code: 'FENCED' });
+    }
+    return member;
+  }
+
+  async heartbeat(membership: Membership): Promise<void> {
+    await withStorageLock(this.lockPath(membership.teamId), async () => {
+      await this.assertOwner(membership);
+      await this.presence.renew(membership);
+    });
+  }
+
+  async leave(membership: Membership): Promise<void> {
+    await withStorageLock(this.lockPath(membership.teamId), async () => {
+      const member = await this.assertOwner(membership);
+      const timestamp = new Date(this.now()).toISOString();
+      await this.teams.updateMember(member.teamId, member.memberId, member.generation, current => ({
+        ...current,
+        state: 'left',
+        leftAt: timestamp,
+        updatedAt: timestamp,
+      }));
+      await this.presence.release(membership).catch(() => {});
+    });
+  }
+
+  async peers(membership: Membership): Promise<readonly PeerStatus[]> {
+    await this.assertOwner(membership);
+    const members = await this.teams.listMembers(membership.teamId);
+    const latest = [...members]
+      .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
+      .filter((member, index, all) => all.findIndex(candidate => candidate.alias === member.alias) === index);
+    return Promise.all(latest.map(async member => ({
+      memberId: member.memberId,
+      alias: member.alias,
+      kind: member.kind,
+      generation: member.generation,
+      status: await this.presence.online(member) ? 'online' as const : 'offline' as const,
+    })));
+  }
+
+  async member(teamId: string, memberId: string): Promise<Member | undefined> {
+    return this.teams.readMember(teamId, memberId);
+  }
+
+  async peerPage(membership: Membership, limit = 50, cursor?: string): Promise<PeerPage> {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('Peer page limit must be between 1 and 100.');
+    const peers = [...await this.peers(membership)]
+      .filter(peer => peer.memberId !== membership.memberId)
+      .sort((a, b) => a.memberId.localeCompare(b.memberId));
+    const remaining = cursor === undefined ? peers : peers.filter(peer => peer.memberId > cursor);
+    const page = remaining.slice(0, limit);
+    const nextCursor = remaining.length > limit ? page.at(-1)?.memberId : undefined;
+    return { peers: page, ...(nextCursor ? { nextCursor } : {}) };
+  }
+
+  async resolveAlias(membership: Membership, alias: string): Promise<PeerStatus> {
+    const peer = (await this.peers(membership)).find(candidate => candidate.alias === alias);
+    if (!peer) throw Object.assign(new Error(`Unknown teammate "${alias}".`), { code: 'NOT_FOUND' });
+    return peer;
+  }
+}