ac-teams 0.0.12 → 0.0.13

package/README.md

@@ -7,7 +7,7 @@ Persistent agent teams for [Pi](https://github.com/earendil-works/pi): shared ta
 Requires Linux, Node 22.19 or newer, and an authenticated `pi` executable on `PATH`. Interactive teams also require `tmux` on `PATH`. Tested with Pi 1.4.0 and 1.5.0.
 
 ```sh
-pi install npm:ac-teams@0.0.4
+pi install npm:ac-teams
 ```
 
 Restart Pi after installation. Use Pi's `/trust` command to save approval for each project directory before launching members there; headless children cannot answer the initial trust prompt.

package/docs/usage.md

@@ -39,7 +39,7 @@ Each team tool call uses one line with a status dot, tool name, action, and resu
 
 The `+N lines` hint shows the hidden detail count. Ctrl+O expands the full request and response JSON; mouse-enabled Pi views also support clicking the row.
 
-Team notification messages remain compact; Ctrl+O expands their labeled fields. UI state colors do not replace the underlying progress, ownership, or dependency fields.
+Tool summaries and team notification previews prefer teammate names over IDs. Message receipt IDs stay out of compact summaries. Ctrl+O expands the original request and response, including IDs. Unknown members fall back to their IDs. UI state colors do not replace the underlying progress, ownership, or dependency fields.
 
 ## Main sessions share one team
 
@@ -159,7 +159,11 @@ Example `team_message` arguments:
 {"action":"send","recipients":["root"],"text":"Parser review complete. No edits; two malformed-input cases need tests."}
 ```
 
-Omit `recipients` to notify all other live members. Explicit sets must contain unique live member IDs; an invalid set rejects the whole send. All team members can read the full history, including direct messages.
+Use exact teammate names (such as `"oom-review"`) or member IDs in `recipients`; IDs remain valid. Omit `recipients` to notify all other live members.
+
+Each recipient must resolve to a different live member. An unknown name, a stopped member, or two entries for the same member rejects the whole send.
+
+Receipts and stored history retain resolved IDs. All team members can read the full history, including direct messages.
 
 ```json
 {"action":"history","after":0,"limit":20}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -7,8 +7,8 @@ import { installTeamFooter, visitMember, showDisplayConfig } from "./terminal-ui
 import { readTelemetry } from "./telemetry.ts";
 import { resolveTeammate, teamsCompletions } from "./commands.ts";
 import { showTeamsPanel } from "./panel.ts";
-import { teamToolRenderers, renderTeamMessage, cleanText } from "./render.ts";
-import { join } from "node:path";
+import { teamToolRenderers, teamMessageRenderer, cleanText } from "./render.ts";
+import { dirname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { existsSync, readdirSync } from "node:fs";
@@ -48,7 +48,13 @@ export default function teams(pi: ExtensionAPI) {
   const teamTools = ["team_agent", "team_task", "team_message"];
   const memberId = () => child ? environment[1]! : team?.member ?? "root";
   const teamId = (ctx: ExtensionContext) => team?.team ?? ctx.sessionManager.getSessionId();
-  pi.registerMessageRenderer("ac-teams", renderTeamMessage);
+  function memberLabels(): Record<string, string> {
+    try {
+      const members = coordinator?.store.state.members ?? readState(child ? dirname(environment[0]!) : join(teamsHome(), teamId(context!))).members;
+      return Object.fromEntries(Object.values(members).map(member => [member.id, memberName(member)]));
+    } catch { return { root: "Main" }; } // A transcript can render before its team is available.
+  }
+  pi.registerMessageRenderer("ac-teams", teamMessageRenderer(memberLabels));
   const warn = (message: string) => context?.ui.notify(message, "warning");
   const notify = (through: number, messages: Message[] = []) => {
     pi.sendMessage({ customType: "ac-teams", content: `New team messages through sequence ${through}. Read team_message history after your last cursor. Reply only with useful updates, not acknowledgements.`, display: true, details: { through, messages } }, { deliverAs: "followUp", triggerTurn: true });
@@ -273,13 +279,13 @@ export default function teams(pi: ExtensionAPI) {
     if (change) report(ctx, change);
   });
   function output(data: unknown) { return { content: [{ type: "text" as const, text: JSON.stringify(data) }], details: data }; }
-  const guidance = "Team launches use real long-lived Pi sessions. Idle members count against the shared ceiling. Use stable member/task IDs; query status and history instead of acknowledging notifications. Limits cover only ac-teams, not other launchers or shell commands.";
+  const guidance = "Team launches use real long-lived Pi sessions. Idle members count against the shared ceiling. Use teammate names for messaging and stable IDs for member control and tasks; query status and history instead of acknowledging notifications. Limits cover only ac-teams, not other launchers or shell commands.";
   const taskTrackingGuidance = "Before delegating a deliverable through team_agent, create or reuse a team_task and include its ID in the member's brief. Use one shared task list for your own work and delegated work; do not create one task per teammate by default. Quick lookups and brief second opinions need no separate task unless their results need coordination or follow-up.";
   pi.registerTool({
     name: "team_agent", label: "Team agent", description: "Launch/resume Pi members, list/status, stop owned subtrees, change root limits, and explicitly clean stopped worktrees. Create or reuse team_task entries for delegated deliverables; quick lookups need no task unless results need coordination or follow-up.",
     promptGuidelines: [guidance, taskTrackingGuidance, "Delegation needs the user's authorization. Give each new member a unique descriptive name (one or two lowercase words, hyphenated if two), plus a bounded brief. Names remain stable on resume. Avoid concurrent writers in the same cwd. Worktrees are opt-in."],
     parameters: AgentSchema,
-    ...teamToolRenderers("team_agent"),
+    ...teamToolRenderers("team_agent", memberLabels),
     async execute(_id, args, _signal, _update, ctx) { return output(await handle("agent", args, ctx)); },
   });
   pi.registerTool({
@@ -294,7 +300,7 @@ export default function teams(pi: ExtensionAPI) {
       "team_task start refuses another owner's task or unfinished dependencies. Complete requires ownership, in-progress work, and acceptance=true. Release clears ownership, returns in-progress work to todo, and leaves done work done. Reopen is explicit and cannot invalidate active or done dependents.",
     ],
     parameters: TaskSchema,
-    ...teamToolRenderers("team_task"),
+    ...teamToolRenderers("team_task", memberLabels),
     async execute(_id, args, _signal, _update, ctx) {
       const data = await handle("task", args, ctx) as TaskView | { tasks: TaskView[]; total: number };
       const compact = (task: TaskView) => ({ id: task.id, number: task.number, label: task.label, title: task.title, status: task.status, owner: task.owner, revision: task.revision, dependencies: task.dependencies, blockedBy: task.blockedBy });
@@ -303,10 +309,10 @@ export default function teams(pi: ExtensionAPI) {
     },
   });
   pi.registerTool({
-    name: "team_message", label: "Team message", description: "Send a persistent direct/team message or read cursor-paged history. Send returns a receipt; history and search return full messages. New messages queue a compact follow-up notification for each recipient.",
+    name: "team_message", label: "Team message", description: "Send a persistent direct/team message to teammate names or IDs, or read cursor-paged history. Send returns a receipt with resolved IDs; history and search return full messages. New messages queue a compact follow-up notification for each recipient.",
     promptGuidelines: ["Do not poll team_message history while waiting for replies; notifications trigger a follow-up turn. On notification, read team_message history after your last read cursor and advance it through the returned messages. An empty result means no newer messages, not that a teammate has finished."],
     parameters: MessageSchema,
-    ...teamToolRenderers("team_message"),
+    ...teamToolRenderers("team_message", memberLabels),
     async execute(_id, args, _signal, _update, ctx) {
       const result = await handle("message", args, ctx);
       if (args.action === "send") {

package/src/render.ts

@@ -46,26 +46,30 @@ function entry(title: string, value: unknown, expanded: boolean, theme: Theme, e
   };
 }
 
-function preview(items: unknown[], count: string, theme: Theme): string {
-  const entries = items.slice(0, 3).map(item => toolSummary(item, theme)).filter(Boolean);
+type MemberLabels = () => Readonly<Record<string, string>>;
+const defaultLabels: MemberLabels = () => ({ root: "Main" });
+const memberLabel = (id: unknown, labels: Readonly<Record<string, string>>) => inline(typeof id === "string" && Object.hasOwn(labels, id) ? labels[id] : id);
+
+function preview(items: unknown[], count: string, theme: Theme, labels: Readonly<Record<string, string>>): string {
+  const entries = items.slice(0, 3).map(item => toolSummary(item, theme, labels)).filter(Boolean);
   if (items.length > 3) entries.push(`+${items.length - 3} more`);
   return [count, ...entries].join(" · ");
 }
 
-function toolSummary(data: unknown, theme: Theme): string {
-  if (Array.isArray(data)) return preview(data, `${data.length} messages`, theme);
+function toolSummary(data: unknown, theme: Theme, labels: Readonly<Record<string, string>>): string {
+  if (Array.isArray(data)) return preview(data, `${data.length} messages`, theme, labels);
   if (data && typeof data === "object") {
     const value = data as Record<string, unknown>;
-    if (Array.isArray(value.members)) return preview(value.members, `${value.members.length} members`, theme);
-    if (Array.isArray(value.tasks)) return preview(value.tasks, value.total === undefined ? `${value.tasks.length} tasks` : `${value.tasks.length} of ${value.total} tasks`, theme);
-    const label = value.title ?? value.name ?? value.brief ?? value.text ?? value.query ?? value.id;
+    if (Array.isArray(value.members)) return preview(value.members, `${value.members.length} members`, theme, labels);
+    if (Array.isArray(value.tasks)) return preview(value.tasks, value.total === undefined ? `${value.tasks.length} tasks` : `${value.tasks.length} of ${value.total} tasks`, theme, labels);
+    const label = value.title ?? value.name ?? value.brief ?? value.text ?? value.query ?? (Array.isArray(value.recipients) ? undefined : value.id === undefined ? undefined : memberLabel(value.id, labels));
     const status = value.status === undefined ? "" : inline(value.status);
     const color = status === "done" ? "success"
       : status === "interrupted" ? "error"
       : status === "busy" || status === "in_progress" ? "accent"
       : status === "todo" || status === "starting" || status === "stopping" ? "warning" : "muted";
     const parts = [status ? theme.fg(color, theme.bold(`[${status}]`)) : "", label === undefined ? "" : inline(label)];
-    if (Array.isArray(value.recipients)) parts.push(`to ${value.recipients.map(inline).join(", ")}`);
+    if (Array.isArray(value.recipients)) parts.push(`${value.from === undefined ? "to" : `${memberLabel(value.from, labels)} →`} ${value.recipients.map(id => memberLabel(id, labels)).join(", ")}`);
     for (const key of ["seq", "limit", "depth"]) {
       if (value[key] !== undefined) parts.push(`${key}: ${inline(value[key])}`);
     }
@@ -74,13 +78,13 @@ function toolSummary(data: unknown, theme: Theme): string {
   return data === undefined || data === null ? "" : inline(data);
 }
 
-export function teamToolRenderers(name: string): ToolRenderers {
+export function teamToolRenderers(name: string, getLabels: MemberLabels = defaultLabels): ToolRenderers {
   return {
     renderShell: "self",
     renderCall(args, theme, context) {
       if (!context.isPartial) return new Container();
       const { action, ...fields } = (args ?? {}) as Record<string, unknown>;
-      const request = toolSummary(fields, theme);
+      const request = toolSummary(fields, theme, getLabels());
       const text = `${theme.fg("warning", "●")} ${theme.fg("toolTitle", name)} · ${inline(action ?? "...")} → running${request ? ` · ${request}` : ""}`;
       return new TruncatedText(text, context.outputPad, 0);
     },
@@ -92,8 +96,9 @@ export function teamToolRenderers(name: string): ToolRenderers {
       if (data === undefined) {
         try { data = JSON.parse(text); } catch { data = text; }
       }
-      const outcome = context.isError ? `error · ${inline(text)}` : toolSummary(data, theme) || "done";
-      const request = toolSummary(fields, theme);
+      const labels = getLabels();
+      const outcome = context.isError ? `error · ${inline(text)}` : toolSummary(data, theme, labels) || "done";
+      const request = toolSummary(fields, theme, labels);
       const heading = `${theme.fg(context.isError ? "error" : "success", "●")} ${theme.fg("toolTitle", name)} · ${inline(action ?? "...")} → ${outcome}${request && !outcome.includes(request) ? ` · ${request}` : ""}`;
       const requestJSON = cleanText(JSON.stringify(context.args, null, 2));
       const responseJSON = cleanText(result.details === undefined ? text : JSON.stringify(result.details, null, 2));
@@ -122,10 +127,15 @@ export function teamToolRenderers(name: string): ToolRenderers {
   };
 }
 
-export const renderTeamMessage: MessageRenderer = (message, { expanded }, theme) => {
-  const details = message.details as { through?: number; messages?: { from: string; text: string; recipients: string[] }[] } | undefined;
-  const recent = details?.messages?.at(-1);
-  const name = (id: string) => id === "root" ? "Main" : id;
-  const preview = recent ? `${name(recent.from)} → ${recent.recipients.map(name).join(", ")} · ${recent.text.split("\n")[0]}` : `Updates through ${details?.through ?? "unknown"}`;
-  return entry("Team message", details ?? { content: message.content }, expanded, theme, false, preview);
-};
+export function teamMessageRenderer(getLabels: MemberLabels = defaultLabels): MessageRenderer {
+  return (message, { expanded }, theme) => {
+    const details = message.details as { through?: number; messages?: { from: string; text: string; recipients: string[] }[] } | undefined;
+    const recent = details?.messages?.at(-1);
+    const labels = getLabels();
+    const name = (id: string) => memberLabel(id, labels);
+    const preview = recent ? `${name(recent.from)} → ${recent.recipients.map(name).join(", ")} · ${recent.text.split("\n")[0]}` : `Updates through ${details?.through ?? "unknown"}`;
+    return entry("Team message", details ?? { content: message.content }, expanded, theme, false, preview);
+  };
+}
+
+export const renderTeamMessage = teamMessageRenderer();

package/src/schemas.ts

@@ -36,7 +36,7 @@ export const TaskSchema = Type.Object({
 }, { additionalProperties: false });
 export const MessageSchema = Type.Object({
   action: Type.Union(["send", "history", "search"].map(v => Type.Literal(v))),
-  recipients: Type.Optional(Type.Array(id, { minItems: 1, maxItems: 100, uniqueItems: true })),
+  recipients: Type.Optional(Type.Array(id, { minItems: 1, maxItems: 100, uniqueItems: true, description: "Exact teammate names or member IDs. Each must resolve to a different live member. Omit to notify all other live members." })),
   text: Type.Optional(text), query: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
   after: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 }, { additionalProperties: false });

package/src/store.ts

@@ -360,8 +360,11 @@ export class Store {
     if (args.action === "send") return this.update(state => {
       const limit = enveloped ? maxMessageText : 16000;
       requireValue(text(args.text, limit), `Message text must be nonempty and at most ${limit} characters`);
-      const recipients = args.recipients === undefined ? Object.values(state.members).filter(member => member.id !== actor && isLive(member)).map(member => member.id) : args.recipients;
-      requireValue(Array.isArray(recipients) && (args.recipients === undefined || recipients.length > 0) && new Set(recipients).size === recipients.length && recipients.every(recipient => typeof recipient === "string" && Object.hasOwn(state.members, recipient) && isLive(state.members[recipient])), "Recipients must be unique live member IDs");
+      const members = Object.values(state.members);
+      requireValue(args.recipients === undefined || Array.isArray(args.recipients), "Recipients must be unique live member names or IDs");
+      const recipients = args.recipients === undefined ? members.filter(member => member.id !== actor && isLive(member)).map(member => member.id)
+        : args.recipients.map(recipient => typeof recipient === "string" ? members.find(member => member.id === recipient || member.name === recipient)?.id : undefined);
+      requireValue((args.recipients === undefined || recipients.length > 0) && new Set(recipients).size === recipients.length && recipients.every((recipient): recipient is string => recipient !== undefined && isLive(state.members[recipient])), "Recipients must be unique live member names or IDs");
       const message = { seq: (state.messages.at(-1)?.seq ?? 0) + 1, id: randomUUID(), from: actor, recipients: [...recipients], text: args.text, time: new Date().toISOString() };
       state.messages.push(message);
       return structuredClone(message);