@trim21/personal-pi-extensions 0.0.208 → 0.0.210

package/src/talk/core.ts

@@ -3,13 +3,13 @@
  * 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. A session in a
- * group sees only its co-members; a session in no group sees only itself.
+ * 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 session.
+ * 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.
  */
@@ -17,7 +17,7 @@
 import { age, formatListing, refusalUnknown, shortAddr } from "./format.js";
 import {
   deleteGroup,
-  groupForSession,
+  groupForAgent,
   isValidGroupName,
   listGroups,
   newGroupId,
@@ -45,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";
@@ -58,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 {
@@ -84,14 +84,14 @@ const SWEEP_INTERVAL_MS = 30 * 60 * 1000;
  * 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);
 }
 
@@ -100,7 +100,7 @@ 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>();
@@ -124,7 +124,7 @@ export class TalkCore {
     return this.self?.addr;
   }
 
-  private requireSelf(): SessionRecord {
+  private requireSelf(): AgentRecord {
     const self = this.self;
     if (!self) throw new Error("Talk core is not started");
     return self;
@@ -132,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);
@@ -141,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.
@@ -150,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);
@@ -183,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
     }
   }
 
@@ -297,32 +297,32 @@ export class TalkCore {
   // ── Outbound ───────────────────────────────────────────────────────────
 
   /**
-   * Session ids of the caller's group members, or null when the caller is in
+   * 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 session.
+   * group change takes effect immediately for every agent.
    */
   private async myGroupMemberIds(): Promise<Set<string> | null> {
     const self = this.requireSelf();
-    const group = await groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     return group ? new Set(group.members) : null;
   }
 
   /**
-   * Resolve a target by its exact session id (uuid). Only co-members of the
-   * caller's group are reachable; a session in no group sees no peers at all.
+   * 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 memberIds = await this.myGroupMemberIds();
-    const others = records.filter((r) => r.addr !== self.addr && memberIds?.has(r.sessionId));
-    const target = others.find((r) => r.sessionId === to);
+    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,
@@ -337,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(),
@@ -351,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 {
@@ -407,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.
    */
@@ -418,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);
@@ -433,10 +431,10 @@ export class TalkCore {
   // ── Tool actions ───────────────────────────────────────────────────────
 
   /**
-   * JSON listing of visible sessions, including self (marked `self: true`).
-   * Grouped sessions see only their co-members; a session in no group sees
+   * 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-session status.
+   * decides the per-agent status.
    */
   async list(): Promise<string> {
     const self = this.requireSelf();
@@ -444,7 +442,7 @@ export class TalkCore {
     const memberIds = await this.myGroupMemberIds();
     const records = all.filter((r) => {
       if (r.addr === self.addr) return !this.dead;
-      return memberIds?.has(r.sessionId) ?? false;
+      return memberIds?.has(r.agentId) ?? false;
     });
     return formatListing(records, self.addr, presenceOf);
   }
@@ -457,30 +455,30 @@ export class TalkCore {
     const filtered = records.filter((r) => {
       if (r.cwd !== cwd) return false;
       if (r.addr === self.addr) return !this.dead;
-      return memberIds?.has(r.sessionId) ?? false;
+      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);
     const memberIds = await this.myGroupMemberIds();
-    return records.filter((r) => r.addr !== self.addr && (memberIds?.has(r.sessionId) ?? false));
+    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;
@@ -494,7 +492,7 @@ 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 ─────────────────────────────────────────────────────────────
@@ -502,9 +500,9 @@ export class TalkCore {
   /** 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 groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     if (!group) return false;
-    const others = group.members.filter((m) => m !== self.sessionId);
+    const others = group.members.filter((m) => m !== self.agentId);
     if (others.length === 0) {
       await deleteGroup(this.storage, group.id);
     } else {
@@ -517,36 +515,42 @@ export class TalkCore {
    * 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.
+   * 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): Promise<string> {
+  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.sessionId)) {
-      return `Already in group ${name} (${existing.members.length} member(s)).`;
+    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.sessionId],
+        members: [...existing.members, self.agentId],
         updatedAt: this.now(),
       });
-      return `Joined group ${name} (${existing.members.length + 1} member(s)). You now see only co-members.`;
+      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.sessionId],
+      members: [self.agentId],
       createdAt: now,
       updatedAt: now,
     });
-    return `Created group ${name}. Other sessions join it with /talk-group-join ${name}.`;
+    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. */
@@ -560,9 +564,9 @@ export class TalkCore {
   /** Leave the current group; an emptied group is deleted. */
   async groupLeave(): Promise<string> {
     const self = this.requireSelf();
-    const group = await groupForSession(this.storage, self.sessionId);
+    const group = await groupForAgent(this.storage, self.agentId);
     if (!group) return "Not in any group.";
-    const others = group.members.filter((m) => m !== self.sessionId);
+    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).`;
@@ -581,7 +585,7 @@ export class TalkCore {
     return `Deleted group ${name} (${group.members.length} member(s)).`;
   }
 
-  /** Delete every group; all sessions become ungrouped. */
+  /** 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);
@@ -597,17 +601,15 @@ export class TalkCore {
     const groups = await listGroups(this.storage);
     if (groups.length === 0) return "No groups.";
     const records = await listRecords(this.storage);
-    const label = (sessionId: string): string => {
-      const rec = records.find((r) => r.sessionId === sessionId);
-      const id = sessionId.length > 8 ? `${sessionId.slice(0, 8)}…` : sessionId;
-      return rec ? `${rec.name} (${id})` : `unknown session (${id})`;
+    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.sessionId ? `${label(m)} ← you` : label(m),
-        );
+        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")}`;
@@ -617,7 +619,7 @@ export class TalkCore {
     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;
@@ -683,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

@@ -1,14 +1,14 @@
 /**
- * Session groups for the talk mailbox: an explicit, uuid-addressed set of
- * sessions that see only each other. Core layer — depends only on
+ * 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:
- * - A session belongs to at most one group (single-group invariant).
- * - Groups are public: any session can join any group by its uuid, and a
+ * - 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 session sees only its
- *   co-members; a session in no group sees only itself.
+ * - 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).
  */
@@ -22,7 +22,7 @@ import type { TalkStorage } from "./storage.js";
 
 export const GroupSchema = Type.Object({
   id: Type.String(),
-  /** pi session uuids of the members. */
+  /** pi agent uuids of the members. */
   members: Type.Array(Type.String()),
   createdAt: Type.Number(),
   updatedAt: Type.Number(),
@@ -79,16 +79,13 @@ export async function deleteGroup(storage: TalkStorage, id: string): Promise<boo
 }
 
 /**
- * The group a session currently belongs to. Under the single-group invariant
- * this is at most one; corrupted data that lists the session in several
+ * 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 groupForSession(
-  storage: TalkStorage,
-  sessionId: string,
-): Promise<Group | null> {
+export async function groupForAgent(storage: TalkStorage, agentId: string): Promise<Group | null> {
   for (const group of await listGroups(storage)) {
-    if (group.members.includes(sessionId)) return group;
+    if (group.members.includes(agentId)) return group;
   }
   return null;
 }