@trim21/personal-pi-extensions 0.0.206 → 0.0.209

package/src/talk/core.ts

@@ -1,18 +1,29 @@
 /**
- * Talk core: coordinates the registry, mailbox, and policy over a storage
- * backend, and yields deliveries and notifications to an adapter through
- * events. Pi-free — the pi adapter (index.ts) owns the pi API surface.
+ * Talk core: coordinates the registry, mailbox, groups, and policy over a
+ * storage backend, and yields deliveries and notifications to an adapter
+ * through events. Pi-free — the pi adapter (index.ts) owns the pi API surface.
+ *
+ * Visibility model: groups are the only visibility boundary. An agent in a
+ * group sees only its co-members; an agent in no group sees only itself.
+ * Membership is read live from storage on every operation, so joining or
+ * leaving a group takes effect immediately for every agent.
  *
  * Delivery model: a letter is removed from the inbox only AFTER the adapter
- * reports it was handed to the session (`events.deliver` returns true). A
+ * reports it was handed to the agent (`events.deliver` returns true). A
  * letter whose delivery fails stays in the inbox and is retried on the next
  * poll — so a swallowed sendMessage error no longer destroys the letter.
  */
 
-import { isAbsolute, resolve } from "node:path";
-
-import { expandHome } from "../lib/path.js";
-import { formatListing, refusalUnknown, shortAddr } from "./format.js";
+import { age, formatListing, refusalUnknown, shortAddr } from "./format.js";
+import {
+  deleteGroup,
+  groupForAgent,
+  isValidGroupName,
+  listGroups,
+  newGroupId,
+  readGroup,
+  writeGroup,
+} from "./group.js";
 import {
   appendAudit,
   awaitReceipt,
@@ -34,12 +45,12 @@ import {
 } from "./mailbox.js";
 import { inboundAccepts, OutboundPolicy } from "./policy.js";
 import {
+  type AgentRecord,
   listRecords,
   type Presence,
   presenceOf,
   readRecord,
   readStartTime,
-  type SessionRecord,
   sweep,
   writeRecord,
 } from "./registry.js";
@@ -47,7 +58,7 @@ import type { TalkStorage } from "./storage.js";
 
 type AskOutcome =
   { replied: true; body: string; from: string } | { replied: false; reason: string };
-type TargetResult = { ok: true; record: SessionRecord } | { ok: false; error: string };
+type TargetResult = { ok: true; record: AgentRecord } | { ok: false; error: string };
 type SendResult = { ok: true; letter: Letter; verdict: string } | { ok: false; error: string };
 
 export interface TalkCoreEvents {
@@ -69,44 +80,18 @@ const DELIVERY_BACKOFF_MS = 5000;
 const INITIAL_DRAIN_DELAY_MS = 1200;
 const SWEEP_INTERVAL_MS = 30 * 60 * 1000;
 
-/** Normalize an allowed path: expand ~, resolve relative against baseCwd, strip trailing slashes. */
-function normalizeAllowedPath(p: string, baseCwd: string): string {
-  const expanded = expandHome(p);
-  const abs = isAbsolute(expanded) ? resolve(expanded) : resolve(baseCwd, expanded);
-  return abs.replace(/[\\/]+$/, "") || "/";
-}
-
-/**
- * Build the workspace-visibility gate for one session. `allowed` is the
- * `allowed` array from `<cwd>/.pi/talk.json` (undefined when the file or key
- * is absent). A peer session is visible when its cwd equals an allowed prefix
- * or sits below it (`prefix` or `prefix/*`); `company1` never matches
- * `company12`. An undefined list shows everything; an explicit empty list
- * shows nothing.
- */
-export function buildVisibilityFilter(
-  allowed: string[] | undefined,
-  baseCwd: string,
-): (peerCwd: string) => boolean {
-  if (allowed === undefined) return () => true;
-  if (allowed.length === 0) return () => false;
-  const prefixes = allowed.map((p) => normalizeAllowedPath(p, baseCwd));
-  return (peerCwd) =>
-    prefixes.some((prefix) => peerCwd === prefix || peerCwd.startsWith(`${prefix}/`));
-}
-
 /**
  * Mutual-ask arbitration: true when the peer asked first. The `ts` fields of
  * the two ask letters are fixed values inside the letters, so both sides
  * compare the same pair and reach symmetric conclusions. On a same-ms
- * collision, `cwd + sessionId` breaks the tie deterministically.
+ * collision, `cwd + agentId` breaks the tie deterministically.
  */
 export function peerAskedFirst(
-  peer: { ts: number; cwd: string; sessionId: string },
-  self: { ts: number; cwd: string; sessionId: string },
+  peer: { ts: number; cwd: string; agentId: string },
+  self: { ts: number; cwd: string; agentId: string },
 ): boolean {
-  const peerKey = `${peer.cwd}\u0000${peer.sessionId}`;
-  const selfKey = `${self.cwd}\u0000${self.sessionId}`;
+  const peerKey = `${peer.cwd}\u0000${peer.agentId}`;
+  const selfKey = `${self.cwd}\u0000${self.agentId}`;
   return peer.ts < self.ts || (peer.ts === self.ts && peerKey < selfKey);
 }
 
@@ -115,14 +100,12 @@ export class TalkCore {
   private readonly events: TalkCoreEvents;
   private readonly now: () => number;
 
-  private self: SessionRecord | undefined;
+  private self: AgentRecord | undefined;
   private readonly policy = new OutboundPolicy();
   private readonly askWaiters = new Map<string, (outcome: AskOutcome) => void>();
   private readonly watched = new Map<string, Presence>();
   /** Message ids already handed to the adapter but not yet removed from the inbox. */
   private readonly deliveredIds = new Set<string>();
-  /** Visibility gate over peer working directories; defaults to everything visible. */
-  private isPeerVisible: (peerCwd: string) => boolean = () => true;
   /** Manually marked dead: offline flag set, lastSeenAt pinned to 0. */
   private dead = false;
 
@@ -141,12 +124,7 @@ export class TalkCore {
     return this.self?.addr;
   }
 
-  /** Replace the peer-visibility gate (from the session's `.pi/talk.json`). */
-  setPeerVisibility(filter: (peerCwd: string) => boolean): void {
-    this.isPeerVisible = filter;
-  }
-
-  private requireSelf(): SessionRecord {
+  private requireSelf(): AgentRecord {
     const self = this.self;
     if (!self) throw new Error("Talk core is not started");
     return self;
@@ -154,7 +132,7 @@ export class TalkCore {
 
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
-  async start(self: SessionRecord): Promise<void> {
+  async start(self: AgentRecord): Promise<void> {
     await this.storage.init();
     // Record the process start time so presence can rule out pid reuse later.
     const pidStart = readStartTime(self.pid);
@@ -163,7 +141,7 @@ export class TalkCore {
     try {
       await sweep(this.storage, this.now());
     } catch {
-      // sweep failure never breaks the session
+      // sweep failure never breaks the agent
     }
     this.startInboxPoll();
     // Reclaim dead records periodically, not just at startup.
@@ -172,7 +150,7 @@ export class TalkCore {
     }, SWEEP_INTERVAL_MS);
     this.sweeper.unref();
     // Drain mail queued while offline — deferred: delivering during
-    // session_start races the session's own first turn.
+    // session_start races the agent's own first turn.
     const initial = setTimeout(() => {
       void this.checkInbox();
     }, INITIAL_DRAIN_DELAY_MS);
@@ -205,18 +183,18 @@ export class TalkCore {
     void this.writeSelf({ status: "idle" });
   }
 
-  setSessionName(name: string): void {
+  setAgentName(name: string): void {
     void this.writeSelf({ name });
   }
 
-  private async writeSelf(patch: Partial<SessionRecord>): Promise<void> {
+  private async writeSelf(patch: Partial<AgentRecord>): Promise<void> {
     if (!this.self) return;
-    // A dead session pins lastSeenAt to 0 so no later event re-freshens it.
+    // A dead agent pins lastSeenAt to 0 so no later event re-freshens it.
     this.self = { ...this.self, ...patch, lastSeenAt: this.dead ? 0 : this.now() };
     try {
       await writeRecord(this.storage, this.self);
     } catch {
-      // registration failures never break the session
+      // registration failures never break the agent
     }
   }
 
@@ -319,21 +297,32 @@ export class TalkCore {
   // ── Outbound ───────────────────────────────────────────────────────────
 
   /**
-   * Resolve a target by its exact session id (uuid). A peer must be visible
-   * from this session (`setPeerVisibility`); invisible peers are unreachable
-   * even with a known id.
+   * Agent ids of the caller's group members, or null when the caller is in
+   * no group. Visibility is read live from storage on every operation, so a
+   * group change takes effect immediately for every agent.
+   */
+  private async myGroupMemberIds(): Promise<Set<string> | null> {
+    const self = this.requireSelf();
+    const group = await groupForAgent(this.storage, self.agentId);
+    return group ? new Set(group.members) : null;
+  }
+
+  /**
+   * Resolve a target by its exact agent id (uuid). Only co-members of the
+   * caller's group are reachable; an agent in no group sees no peers at all.
    */
   private async resolveTarget(to: string): Promise<TargetResult> {
     const self = this.requireSelf();
     const records = await listRecords(this.storage);
-    const others = records.filter((r) => r.addr !== self.addr && this.isPeerVisible(r.cwd));
-    const target = others.find((r) => r.sessionId === to);
+    const memberIds = await this.myGroupMemberIds();
+    const others = records.filter((r) => r.addr !== self.addr && memberIds?.has(r.agentId));
+    const target = others.find((r) => r.agentId === to);
     if (!target) return { ok: false, error: refusalUnknown(to) };
     return { ok: true, record: target };
   }
 
   private async sendLetter(
-    target: SessionRecord,
+    target: AgentRecord,
     kind: LetterKind,
     body: string,
     replyTo?: string,
@@ -348,7 +337,7 @@ export class TalkCore {
     if (!verdict.ok) return { ok: false, error: verdict.reason };
     const letter: Letter = {
       id: newMessageId(),
-      from: { addr: self.addr, name: self.name, cwd: self.cwd, sessionId: self.sessionId },
+      from: { addr: self.addr, name: self.name, cwd: self.cwd, agentId: self.agentId },
       kind,
       body,
       ts: this.now(),
@@ -362,9 +351,7 @@ export class TalkCore {
         ok: true,
         letter,
         verdict:
-          receipt === "delivered"
-            ? "delivered"
-            : "queued (waits on disk until the session resumes)",
+          receipt === "delivered" ? "delivered" : "queued (waits on disk until the agent resumes)",
       };
     }
     return {
@@ -418,7 +405,7 @@ export class TalkCore {
    * - the later ask yields: its waiter is settled with a "peer asked first"
    *   reason, and the peer's ask is delivered so this side answers it first.
    *
-   * On a same-millisecond ts collision, session dir + session id (carried in
+   * On a same-millisecond ts collision, agent dir + agent id (carried in
    * `letter.from`) breaks the tie deterministically — both sides compute the
    * same comparison and reach symmetric conclusions.
    */
@@ -429,8 +416,8 @@ export class TalkCore {
     const waiter = this.askWaiters.get(myAsk.askId);
     if (!waiter) return;
     const peerFirst = peerAskedFirst(
-      { ts: letter.ts, cwd: letter.from.cwd, sessionId: letter.from.sessionId },
-      { ts: myAsk.ts, cwd: self.cwd, sessionId: self.sessionId },
+      { ts: letter.ts, cwd: letter.from.cwd, agentId: letter.from.agentId },
+      { ts: myAsk.ts, cwd: self.cwd, agentId: self.agentId },
     );
     if (!peerFirst) return; // we asked first; keep waiting — the peer will yield
     this.askWaiters.delete(myAsk.askId);
@@ -444,16 +431,18 @@ export class TalkCore {
   // ── Tool actions ───────────────────────────────────────────────────────
 
   /**
-   * JSON listing of visible sessions, including self (marked `self: true`).
-   * Every visible record is listed, live or offline; presence decides the
-   * per-session status.
+   * JSON listing of visible agents, including self (marked `self: true`).
+   * Grouped agents see only their co-members; an agent in no group sees
+   * only itself. Every visible record is listed, live or offline; presence
+   * decides the per-agent status.
    */
   async list(): Promise<string> {
     const self = this.requireSelf();
     const all = await listRecords(this.storage);
+    const memberIds = await this.myGroupMemberIds();
     const records = all.filter((r) => {
       if (r.addr === self.addr) return !this.dead;
-      return this.isPeerVisible(r.cwd);
+      return memberIds?.has(r.agentId) ?? false;
     });
     return formatListing(records, self.addr, presenceOf);
   }
@@ -462,32 +451,34 @@ export class TalkCore {
   async listCwd(cwd: string): Promise<string> {
     const self = this.requireSelf();
     const records = await listRecords(this.storage);
+    const memberIds = await this.myGroupMemberIds();
     const filtered = records.filter((r) => {
       if (r.cwd !== cwd) return false;
       if (r.addr === self.addr) return !this.dead;
-      return this.isPeerVisible(r.cwd);
+      return memberIds?.has(r.agentId) ?? false;
     });
     return formatListing(filtered, self.addr, presenceOf);
   }
 
   /** Visible peer records (excluding self), e.g. for command completions. */
-  async listPeers(): Promise<SessionRecord[]> {
+  async listPeers(): Promise<AgentRecord[]> {
     const self = this.requireSelf();
     const records = await listRecords(this.storage);
-    return records.filter((r) => r.addr !== self.addr && this.isPeerVisible(r.cwd));
+    const memberIds = await this.myGroupMemberIds();
+    return records.filter((r) => r.addr !== self.addr && (memberIds?.has(r.agentId) ?? false));
   }
 
   /**
-   * Mark a session as dead: set its offline flag and pin lastSeenAt to 0 so
+   * Mark an agent as dead: set its offline flag and pin lastSeenAt to 0 so
    * the next sweep reaps it (empty mailbox). Without a target, marks this
-   * session — later writeSelf calls no longer refresh lastSeenAt, and the
+   * agent — later writeSelf calls no longer refresh lastSeenAt, and the
    * record stays offline for peers.
    */
   async markDead(target?: string): Promise<string> {
     if (!target) {
       this.dead = true;
       await this.writeSelf({ offline: true });
-      return "Marked this session as dead.";
+      return "Marked this agent as dead.";
     }
     const resolved = await this.resolveTarget(target);
     if (!resolved.ok) return resolved.error;
@@ -501,14 +492,134 @@ export class TalkCore {
     for (const peer of peers) {
       await writeRecord(this.storage, { ...peer, lastSeenAt: 0, offline: true });
     }
-    return `Marked ${peers.length} session(s) as dead.`;
+    return `Marked ${peers.length} agent(s) as dead.`;
+  }
+
+  // ── Groups ─────────────────────────────────────────────────────────────
+
+  /** Remove the caller from its current group, deleting the group when it empties. */
+  private async leaveCurrentGroup(): Promise<boolean> {
+    const self = this.requireSelf();
+    const group = await groupForAgent(this.storage, self.agentId);
+    if (!group) return false;
+    const others = group.members.filter((m) => m !== self.agentId);
+    if (others.length === 0) {
+      await deleteGroup(this.storage, group.id);
+    } else {
+      await writeGroup(this.storage, { ...group, members: others, updatedAt: this.now() });
+    }
+    return true;
+  }
+
+  /**
+   * Join or create a group and join it. With no name a fresh uuid is
+   * generated; with a name, the group is joined when it exists and created
+   * otherwise. Leaving any current group first keeps the single-group
+   * invariant. When `agentName` is given, the agent's display name (what
+   * peers see in talk-list-agents) is set to it — also when the agent is
+   * already in the group, so re-joining can rename.
+   */
+  async groupJoin(groupName?: string, agentName?: string): Promise<string> {
+    const self = this.requireSelf();
+    const name =
+      groupName === undefined || groupName.trim() === "" ? newGroupId() : groupName.trim();
+    if (!isValidGroupName(name)) {
+      return `Invalid group name '${name}'. Allowed: letters, digits, '-' and '_' (max 64 chars).`;
+    }
+    if (agentName !== undefined) {
+      await this.writeSelf({ name: agentName });
+    }
+    const nameNote = agentName === undefined ? "" : ` You are visible as "${agentName}".`;
+    const existing = await readGroup(this.storage, name);
+    if (existing?.members.includes(self.agentId)) {
+      return `Already in group ${name} (${existing.members.length} member(s)).${nameNote}`;
+    }
+    await this.leaveCurrentGroup();
+    if (existing) {
+      await writeGroup(this.storage, {
+        ...existing,
+        members: [...existing.members, self.agentId],
+        updatedAt: this.now(),
+      });
+      return `Joined group ${name} (${existing.members.length + 1} member(s)). You now see only co-members.${nameNote}`;
+    }
+    const now = this.now();
+    await writeGroup(this.storage, {
+      id: name,
+      members: [self.agentId],
+      createdAt: now,
+      updatedAt: now,
+    });
+    return `Created group ${name}.${nameNote} Other agents join it with /talk-group-join ${name}.`;
+  }
+
+  /** Join the most recently created group; no-op when already in it. */
+  async groupJoinLast(): Promise<string> {
+    const groups = await listGroups(this.storage);
+    if (groups.length === 0) return "No groups. Create one with /talk-group-join.";
+    const latest = groups.reduce((a, b) => (b.createdAt > a.createdAt ? b : a));
+    return this.groupJoin(latest.id);
+  }
+
+  /** Leave the current group; an emptied group is deleted. */
+  async groupLeave(): Promise<string> {
+    const self = this.requireSelf();
+    const group = await groupForAgent(this.storage, self.agentId);
+    if (!group) return "Not in any group.";
+    const others = group.members.filter((m) => m !== self.agentId);
+    if (others.length === 0) {
+      await deleteGroup(this.storage, group.id);
+      return `Left group ${group.id} (deleted — it was empty).`;
+    }
+    await writeGroup(this.storage, { ...group, members: others, updatedAt: this.now() });
+    return `Left group ${group.id} (${others.length} member(s) remain).`;
+  }
+
+  /** Delete a group by name; its members become ungrouped. */
+  async groupDelete(groupName: string): Promise<string> {
+    const name = groupName.trim();
+    if (!isValidGroupName(name)) return `Invalid group name '${name}'.`;
+    const group = await readGroup(this.storage, name);
+    if (!group) return `Unknown group '${name}'. Run /talk-group-list to see groups.`;
+    await deleteGroup(this.storage, name);
+    return `Deleted group ${name} (${group.members.length} member(s)).`;
+  }
+
+  /** Delete every group; all agents become ungrouped. */
+  async groupClear(): Promise<string> {
+    const groups = await listGroups(this.storage);
+    for (const group of groups) await deleteGroup(this.storage, group.id);
+    return groups.length === 0 ? "No groups." : `Deleted ${groups.length} group(s).`;
+  }
+
+  /**
+   * Human-readable listing of every group and its members (management view).
+   * Newest first — the oldest group is listed last.
+   */
+  async groupList(): Promise<string> {
+    const self = this.requireSelf();
+    const groups = await listGroups(this.storage);
+    if (groups.length === 0) return "No groups.";
+    const records = await listRecords(this.storage);
+    const label = (agentId: string): string => {
+      const rec = records.find((r) => r.agentId === agentId);
+      const id = agentId.length > 8 ? `${agentId.slice(0, 8)}…` : agentId;
+      return rec ? `${rec.name} (${id})` : `unknown agent (${id})`;
+    };
+    const lines = groups
+      .toSorted((a, b) => b.createdAt - a.createdAt)
+      .map((g) => {
+        const members = g.members.map((m) => (m === self.agentId ? `${label(m)} ← you` : label(m)));
+        return `- ${g.id} (created ${age(g.createdAt)}): ${members.join(", ")}`;
+      });
+    return `Groups (${groups.length}):\n${lines.join("\n")}`;
   }
 
   async send(to: string, body: string): Promise<string> {
     if (!to) return 'send requires "to".';
     if (!body) return 'send requires "message".';
     if (to === "*" || to === "cwd") {
-      return "send requires a single session id; broadcasting is disabled.";
+      return "send requires a single agent id; broadcasting is disabled.";
     }
     const resolved = await this.resolveTarget(to);
     if (!resolved.ok) return resolved.error;
@@ -574,10 +685,10 @@ export class TalkCore {
   }
 
   /** Build a minimal record from a letter's sender when the peer record is gone. */
-  private recordFromLetter(letter: Letter): SessionRecord {
+  private recordFromLetter(letter: Letter): AgentRecord {
     return {
       addr: letter.from.addr,
-      sessionId: letter.from.sessionId,
+      agentId: letter.from.agentId,
       name: letter.from.name,
       cwd: letter.from.cwd,
       pid: 0,

package/src/talk/format.ts

@@ -4,10 +4,9 @@
  */
 
 import type { Letter } from "./mailbox.js";
-import type { Presence, SessionRecord } from "./registry.js";
+import type { AgentRecord, Presence } from "./registry.js";
 
-export const BOUNDARY_PREAMBLE =
-  "This came from another pi session (a peer agent), not from the user.";
+export const BOUNDARY_PREAMBLE = "This came from another pi agent, not from the user.";
 
 export function shortAddr(addr: string): string {
   return addr.slice(0, 6);
@@ -21,20 +20,20 @@ export function age(ts: number, now: number = Date.now()): string {
   return `${Math.round(m / 60)}h ago`;
 }
 
-/** Delivery text injected into the receiving session's LLM context. */
+/** Delivery text injected into the receiving agent's LLM context. */
 export function formatDelivery(letter: Letter, now: number = Date.now()): string {
   const from = letter.from;
-  const header = `From pi session ${from.sessionId} (${from.cwd}) — "${from.name}"`;
+  const header = `From pi agent ${from.agentId} (${from.cwd}) — "${from.name}"`;
   const meta = `_id ${letter.id} · ${letter.kind} · sent ${age(letter.ts, now)}_`;
   const hint =
     letter.kind === "ask" ? `\n\nReply with the talk-reply tool, replyTo: "${letter.id}"` : "";
   return `${BOUNDARY_PREAMBLE}\n\n${header}:\n\n${letter.body}\n\n${meta}${hint}`;
 }
 
-/** One session as the model sees it in a listing. `id` is the stable pi
- * session uuid; `name` is the display name when one was set; `self` marks
- * the calling session itself. */
-export interface SessionListItem {
+/** One agent as the model sees it in a listing. `id` is the stable pi
+ * agent uuid; `name` is the display name when one was set; `self` marks
+ * the calling agent itself. */
+export interface AgentListItem {
   status: string;
   work_dir: string;
   id: string;
@@ -42,17 +41,17 @@ export interface SessionListItem {
   self?: boolean;
 }
 
-/** Machine-readable JSON listing of sessions (what the model sees). */
+/** Machine-readable JSON listing of agents (what the model sees). */
 export function formatListing(
-  records: SessionRecord[],
+  records: AgentRecord[],
   selfAddr: string,
-  presence: (r: SessionRecord) => Presence,
+  presence: (r: AgentRecord) => Presence,
 ): string {
   if (records.length === 0) return "[]";
-  const items: SessionListItem[] = records.map((r) => {
+  const items: AgentListItem[] = records.map((r) => {
     const p = presence(r);
     const status = p === "live" ? r.status : "offline";
-    const item: SessionListItem = { status, work_dir: r.cwd, id: r.sessionId, name: r.name };
+    const item: AgentListItem = { status, work_dir: r.cwd, id: r.agentId, name: r.name };
     if (r.addr === selfAddr) item.self = true;
     return item;
   });
@@ -60,5 +59,5 @@ export function formatListing(
 }
 
 export function refusalUnknown(to: string): string {
-  return `Unknown session id '${to}'. Get session ids with talk-list-sessions.`;
+  return `Unknown agent id '${to}'. Get agent ids with talk-list-agents.`;
 }

package/src/talk/group.ts

@@ -0,0 +1,91 @@
+/**
+ * Agent groups for the talk mailbox: an explicit, uuid-addressed set of
+ * agents that see only each other. Core layer — depends only on
+ * TalkStorage, never on pi.
+ *
+ * Rules:
+ * - An agent belongs to at most one group (single-group invariant).
+ * - Groups are public: any agent can join any group by its uuid, and a
+ *   member can leave freely. There is no owner.
+ * - Visibility is fully group-driven: a grouped agent sees only its
+ *   co-members; an agent in no group sees only itself.
+ * - A group that empties is deleted; a one-member group is a normal state
+ *   (a creator waiting for peers to join).
+ */
+
+import { randomUUID } from "node:crypto";
+
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+import type { TalkStorage } from "./storage.js";
+
+export const GroupSchema = Type.Object({
+  id: Type.String(),
+  /** pi agent uuids of the members. */
+  members: Type.Array(Type.String()),
+  createdAt: Type.Number(),
+  updatedAt: Type.Number(),
+});
+export type Group = Static<typeof GroupSchema>;
+
+export const GROUPS_NS = "groups";
+
+/**
+ * Group names are user-facing and become storage keys, so they are
+ * constrained: start with a letter/digit, then letters, digits, '-' or '_'.
+ * A generated uuid fits this pattern too.
+ */
+const GROUP_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+export function assertGroupId(id: string): void {
+  if (!GROUP_ID_PATTERN.test(id)) throw new TypeError(`Invalid group name: ${id}`);
+}
+
+export function isValidGroupName(id: string): boolean {
+  return GROUP_ID_PATTERN.test(id);
+}
+
+export function newGroupId(): string {
+  return randomUUID();
+}
+
+function groupKey(id: string): string {
+  assertGroupId(id);
+  return `${id}.json`;
+}
+
+/** All groups, oldest first. Never mutates anything. */
+export async function listGroups(storage: TalkStorage): Promise<Group[]> {
+  const out: Group[] = [];
+  for (const key of await storage.listKeys(GROUPS_NS)) {
+    const raw = await storage.readJson(GROUPS_NS, key);
+    if (Value.Check(GroupSchema, raw)) out.push(raw);
+  }
+  return out.toSorted((a, b) => a.createdAt - b.createdAt);
+}
+
+export async function readGroup(storage: TalkStorage, id: string): Promise<Group | null> {
+  const raw = await storage.readJson(GROUPS_NS, groupKey(id));
+  return Value.Check(GroupSchema, raw) ? raw : null;
+}
+
+export async function writeGroup(storage: TalkStorage, group: Group): Promise<void> {
+  await storage.writeJson(GROUPS_NS, groupKey(group.id), group);
+}
+
+export async function deleteGroup(storage: TalkStorage, id: string): Promise<boolean> {
+  return storage.removeKey(GROUPS_NS, groupKey(id));
+}
+
+/**
+ * The group an agent currently belongs to. Under the single-group invariant
+ * this is at most one; corrupted data that lists the agent in several
+ * groups resolves to the first match.
+ */
+export async function groupForAgent(storage: TalkStorage, agentId: string): Promise<Group | null> {
+  for (const group of await listGroups(storage)) {
+    if (group.members.includes(agentId)) return group;
+  }
+  return null;
+}