@ctliz/agent-intercom-pi 0.12.2 → 0.14.0

package/named-team-membership.ts

@@ -0,0 +1,124 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { ensureIntercomRuntimeDir, getAgentDirPath, getIntercomDirPath } from "./broker/paths.ts";
+import { writeDurableJson } from "./durable-json.ts";
+import { generateNamedTeamScope, listNamedTeams, NAMED_TEAMS_FILE, NAMED_TEAMS_VERSION, parseTeamName, type NamedTeam } from "./named-teams.ts";
+import type { SessionInfo } from "./types.ts";
+
+export function namedTeamMemberIds(team: NamedTeam): string[] {
+  return team.memberSessionIds ?? [team.managerSessionId];
+}
+
+export function sessionNamedTeams(sessionId: string, agentDir?: string): NamedTeam[] {
+  return listNamedTeams(agentDir).filter((team) => namedTeamMemberIds(team).includes(sessionId));
+}
+
+/** Serialize the complete read-modify-write across independently launched Pi processes. */
+export async function appendNamedTeamMembership(input: {
+  name: string;
+  selfId: string;
+  members?: string[];
+  create?: boolean;
+  work?: string;
+  agentDir?: string;
+}): Promise<NamedTeam> {
+  const name = parseTeamName(input.name);
+  const memberIds = [...new Set([input.selfId, ...(input.members ?? [])])];
+  if (memberIds.some((id) => !id || id.trim() !== id || /[\u0000-\u001f\u007f]/.test(id))) {
+    throw new Error("Invalid team member session ID");
+  }
+  if (input.work !== undefined && (!input.work.trim() || input.work.length > 2000)) {
+    throw new Error("Work must be a non-empty task description (max 2000 characters)");
+  }
+  const dir = getIntercomDirPath(input.agentDir ?? getAgentDirPath());
+  ensureIntercomRuntimeDir(dir);
+  const lock = join(dir, "named-teams.lock");
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    try {
+      mkdirSync(lock, { mode: 0o700 });
+      break;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new Error("Team registry is busy; retry. If a writer crashed, remove the stale named-teams.lock directory after verifying no writer is active.");
+      await delay(25);
+    }
+  }
+  try {
+    const teams = listNamedTeams(input.agentDir);
+    let team = teams.find((entry) => entry.name === name);
+    if (input.create) {
+      if (team) throw new Error(`A named team called ${name} already exists; join it instead.`);
+      team = { name, scopeId: generateNamedTeamScope(teams.map((entry) => entry.scopeId)), managerSessionId: input.selfId, createdAt: Date.now() };
+      teams.push(team);
+    }
+    if (!team) throw new Error(`Team "${name}" does not exist; create it explicitly.`);
+    if (memberIds.some((id) => id !== input.selfId) && team.managerSessionId !== input.selfId) {
+      throw new Error(`Only the manager of team "${name}" may add other sessions`);
+    }
+    if (input.work !== undefined && !input.create) {
+      throw new Error("Work is set when creating a team; use a new team for a different task");
+    }
+    const updated: NamedTeam = {
+      ...team,
+      memberSessionIds: [...new Set([...namedTeamMemberIds(team), ...memberIds])],
+      ...(input.work === undefined ? {} : { work: input.work.trim() }),
+    };
+    writeDurableJson(join(dir, NAMED_TEAMS_FILE), {
+      version: NAMED_TEAMS_VERSION,
+      teams: teams.map((entry) => entry.name === name ? updated : entry),
+    });
+    return updated;
+  } finally {
+    rmSync(lock, { recursive: true });
+  }
+}
+
+export function requireNamedTeamMembers(name: string, selfId: string, peerId: string, agentDir?: string): NamedTeam {
+  const team = listNamedTeams(agentDir).find((entry) => entry.name === name);
+  if (!team) throw new Error(`Unknown team "${name}"`);
+  const members = namedTeamMemberIds(team);
+  if (!members.includes(selfId) || !members.includes(peerId)) {
+    throw new Error(`Both sessions must belong to team "${name}" before messaging`);
+  }
+  return team;
+}
+
+export function resolveNamedMessageTeam(selfId: string, peerId: string, requested?: string, agentDir?: string): string | undefined {
+  if (requested !== undefined) return requireNamedTeamMembers(requested, selfId, peerId, agentDir).name;
+  const mine = sessionNamedTeams(selfId, agentDir);
+  const shared = mine.filter((team) => namedTeamMemberIds(team).includes(peerId));
+  if (shared.length === 1) return shared[0]!.name;
+  if (shared.length > 1) throw new Error("Multiple shared teams; specify `team` for this task");
+  // No shared team means an ungrouped contact, even when either session belongs
+  // to unrelated teams. Do not silently create a team or add the recipient.
+  return undefined;
+}
+
+export function namedTeamRoster(team: NamedTeam, selfId: string, sessions: SessionInfo[]) {
+  return {
+    name: team.name,
+    ...(team.work ? { work: team.work } : {}),
+    self: { id: selfId, isManager: selfId === team.managerSessionId },
+    manager: { target: team.managerSessionId, connected: sessions.some((entry) => entry.id === team.managerSessionId) },
+    members: namedTeamMemberIds(team).map((id) => ({
+      id,
+      target: id,
+      name: sessions.find((entry) => entry.id === id)?.name,
+      role: id === team.managerSessionId ? "manager" : "member",
+      connected: sessions.some((entry) => entry.id === id),
+    })),
+  };
+}
+
+export function formatNamedTeamRoster(team: ReturnType<typeof namedTeamRoster>): string {
+  return [
+    `Team: ${team.name}`,
+    ...(team.work ? [`Work: ${team.work}`] : []),
+    `You: ${team.self.id}${team.self.isManager ? " [manager]" : ""}`,
+    `Manager: ${team.manager.target}${team.manager.connected ? "" : " [offline]"}`,
+    "Members:",
+    ...team.members.map((member) => `- ${member.name || member.id} (${member.id}) [${member.role}]${member.connected ? "" : " [offline]"}`),
+  ].join("\n");
+}

package/named-teams.ts

@@ -14,6 +14,9 @@ export interface NamedTeam {
   scopeId: string;
   managerSessionId: string;
   createdAt: number;
+  /** Pi task-team membership; absent in legacy single-scope teams. */
+  memberSessionIds?: string[];
+  work?: string;
 }
 
 export type JoinableCircleKind = "named" | "tmuxdeck";
@@ -57,11 +60,20 @@ function parseStoredTeam(value: unknown): NamedTeam | undefined {
   if (typeof value.createdAt !== "number" || !Number.isSafeInteger(value.createdAt) || value.createdAt <= 0) {
     return undefined;
   }
+  if (value.memberSessionIds !== undefined && (
+    !Array.isArray(value.memberSessionIds)
+    || !value.memberSessionIds.every((id) => typeof id === "string" && id.trim() === id && id.length > 0 && !/[\u0000-\u001f\u007f]/.test(id))
+    || new Set(value.memberSessionIds).size !== value.memberSessionIds.length
+    || !value.memberSessionIds.includes(value.managerSessionId)
+  )) return undefined;
+  if (value.work !== undefined && (typeof value.work !== "string" || !value.work.trim() || value.work.length > 2000)) return undefined;
   return {
     name: value.name,
     scopeId: value.scopeId,
     managerSessionId: value.managerSessionId,
     createdAt: value.createdAt,
+    ...(value.memberSessionIds === undefined ? {} : { memberSessionIds: value.memberSessionIds as string[] }),
+    ...(value.work === undefined ? {} : { work: value.work as string }),
   };
 }
 

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Pi coding-agent intercom for local messaging with Codex, Claude Code, OpenCode, Grok Build, and AGY agents.",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.ts",
+  "bin": {
+    "intercom-send": "./bin/intercom-send.mjs"
+  },
   "exports": {
     ".": "./index.ts"
   },
   "files": [
     "banner.png",
+    "bin/*.mjs",
     "*.ts",
     "!*.test.ts",
     "broker/**/*.ts",
@@ -54,14 +58,20 @@
   },
   "dependencies": {
     "@ctliz/agent-intercom-core": "0.2.0",
+    "tsx": "^4.20.0"
+  },
+  "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
-    "tsx": "^4.20.0",
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": "^1.0.0",
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^22.15.0",
+    "typebox": "*",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/reply-tracker.ts

@@ -21,6 +21,10 @@ export function pendingAskId(fromSessionId: string, messageId: string): string {
   return `ask-${digest}`;
 }
 
+export function replyContextId(fromSessionId: string, messageId: string): string {
+  return pendingAskId(fromSessionId, messageId).replace(/^ask-/, "ctx-");
+}
+
 function matchesPendingSender(context: IntercomContext, to: string): boolean {
   if (context.from.id === to) {
     return true;
@@ -91,8 +95,23 @@ export class ReplyTracker {
     this.currentTurnContexts = [];
   }
 
-  resolveReplyTarget(options: { to?: string; replyTo?: string; askId?: string; which?: ReplyWhich }, now = Date.now()): IntercomContext {
+  resolveReplyTarget(options: { to?: string; replyTo?: string; askId?: string; which?: ReplyWhich; team?: string; contextId?: string }, now = Date.now()): IntercomContext {
     this.pruneExpired(now);
+    const checkTeam = (context: IntercomContext): IntercomContext => {
+      if (options.team !== undefined && context.message.content.team !== options.team) {
+        throw new Error("Reply team must match the original message; it cannot be changed");
+      }
+      return context;
+    };
+    if (options.contextId) {
+      const match = [...this.currentTurnContexts, ...this.pendingAsks.values()].find((context) =>
+        replyContextId(context.from.id, context.message.id) === options.contextId
+      );
+      if (!match) throw new Error(`No active message with context ID "${options.contextId}"`);
+      if (options.to && !matchesPendingSender(match, options.to)) throw new Error("Reply context is not from the selected sender");
+      if (options.askId && pendingAskId(match.from.id, match.message.id) !== options.askId) throw new Error("Reply selectors refer to different messages");
+      return checkTeam(match);
+    }
 
     if (options.askId) {
       const match = Array.from(this.pendingAsks.values()).find((context) =>
@@ -104,7 +123,7 @@ export class ReplyTracker {
       if (options.to && !matchesPendingSender(match, options.to)) {
         throw new Error(`Pending ask "${options.askId}" is not from "${options.to}"`);
       }
-      return match;
+      return checkTeam(match);
     }
 
     if (options.replyTo) {
@@ -119,13 +138,18 @@ export class ReplyTracker {
       if (matches.length > 1) {
         throw new Error(`Multiple pending asks use message ID "${options.replyTo}" — specify \`to\``);
       }
-      return matches[0]!;
+      return checkTeam(matches[0]!);
     }
 
-    if (this.currentTurnContexts.length > 0) {
+    const inTeam = (context: IntercomContext) => options.team === undefined || context.message.content.team === options.team;
+    const currentTurnContexts = this.currentTurnContexts.filter(inTeam);
+    if (currentTurnContexts.length > 0) {
       const turnMatches = options.to
-        ? this.currentTurnContexts.filter((context) => matchesPendingSender(context, options.to!))
-        : this.currentTurnContexts;
+        ? currentTurnContexts.filter((context) => matchesPendingSender(context, options.to!))
+        : currentTurnContexts;
+      if (new Set(turnMatches.map((context) => context.message.content.team)).size > 1) {
+        throw new Error("Messages from multiple teams are active — specify `contextId`, `askId`, or `team`");
+      }
       const replyableMatches = turnMatches.filter((context) => context.message.expectsReply);
       if (replyableMatches.length === 1) {
         return replyableMatches[0]!;
@@ -146,14 +170,13 @@ export class ReplyTracker {
       }
     }
 
-    const pending = Array.from(this.pendingAsks.values());
-    if (pending.length === 1) {
-      return pending[0]!;
-    }
-
+    const pending = Array.from(this.pendingAsks.values()).filter(inTeam);
     const matches = options.to
       ? pending.filter((context) => matchesPendingSender(context, options.to!))
       : pending;
+    if (new Set(matches.map((context) => context.message.content.team)).size > 1) {
+      throw new Error("Pending asks belong to multiple teams — specify `askId` or `team`");
+    }
     if (matches.length === 1) return matches[0]!;
     if (matches.length > 1) {
       if (!options.to && distinctSenders(matches) > 1) {
@@ -174,9 +197,9 @@ export class ReplyTracker {
     this.dismissPendingAsk(replyTo, fromSessionId);
   }
 
-  dismissOrdinarySender(fromSessionId: string): void {
+  dismissOrdinarySender(fromSessionId: string, messageId?: string): void {
     this.currentTurnContexts = this.currentTurnContexts.filter((context) =>
-      context.message.expectsReply || context.from.id !== fromSessionId
+      context.message.expectsReply || context.from.id !== fromSessionId || (messageId !== undefined && context.message.id !== messageId)
     );
   }
 

package/skills/pi-intercom/SKILL.md

@@ -2,8 +2,8 @@
 name: pi-intercom
 description: |
   Streamline session-to-session coordination with pi-intercom. Send messages,
-  delegate tasks, and coordinate work across multiple pi sessions on the same
-  machine. Use for planner-worker workflows, cross-session context sharing,
+  delegate tasks, and form task teams after user approval across multiple Pi
+  sessions on the same machine. Use for planner-worker workflows, cross-session context sharing,
   and real-time collaboration between sessions.
 ---
 
@@ -24,6 +24,73 @@ This skill covers how to handle those orchestrator-side escalations.
 - **Clarification loops**: Worker asks questions, planner answers, work continues
 - **Multi-session workflows**: Coordinate between specialized sessions (frontend/backend, research/implementation)
 
+## Task Teams: Ask Once, Then Organize (Pi 0.14+)
+
+Independently opened Pi sessions do not form a team merely by sharing a directory.
+When the user asks you to collaborate with named sessions (for example `front`
+and `writer`) or delegate work, and this task has no approved team, ask once:
+
+> 要把我、front、writer 组成一个 team 来负责这个任务吗？
+
+Wait for approval before creating a team or adding peers. An explicit instruction
+to create/join a team is already approval. Do not ask again for the same approved
+team, and do not prompt the user when replying to an inbound team message. If the
+user declines, do not repeatedly ask or silently create a team. Without a shared
+team, omit `team` to send an ungrouped direct message, even if either session
+belongs to unrelated teams. This allows initial contact before forming a team.
+Explicit team messages still require both sessions to be members; multiple
+shared teams still require selecting the intended task team.
+
+After approval, discover the named sessions and form the team in one operation:
+
+```typescript
+intercom_list({})
+intercom_join({
+  name: "launch",
+  create: true,
+  members: ["front", "writer"],
+  work: "Build the product page; front owns UI, writer owns copy",
+})
+intercom_send({ team: "launch", to: "front", message: "Implement the product page UI." })
+intercom_send({ team: "launch", to: "writer", message: "Write the product page copy." })
+```
+
+The creator is the manager of this task team and does not need a `/name`.
+Members are resolved to stable session IDs; no user needs to join each terminal
+manually. Only the manager can add other sessions with `members`; a session can
+join itself with `intercom_join({ name: "launch" })`. Joining appends membership
+without leaving other named teams or changing their managers. The approved
+manager can append a new approved peer with
+`intercom_join({ name: "launch", members: ["reviewer"] })`.
+
+Reuse the team for this task, not for every message. A different task may need a
+different team even with identical participants. `intercom_team({})` shows all
+your named teams; `intercom_team({ team: "launch" })` inspects one.
+
+Messages carry their team separately from their text. Read each `[Team: ...]`
+label independently, including mixed-team batches. Use the exact `contextId`
+reply hint to answer ordinary messages, or `askId` from `intercom_pending` for
+asks. `intercom_reply` inherits the original message's team; never choose a reply
+team using a mutable current-team setting. When peers share multiple teams,
+explicitly pass `team` to sends and asks. Ambiguous replies fail rather than guess.
+
+This is Pi-local task grouping, not a broker security boundary or separate model
+history for each team. Other adapters and managed-team integrations are unchanged;
+all participating Pi sessions must load adapter 0.14.0 or newer.
+
+## Codemode (Pi 0.99.1+)
+
+Active Intercom tools can be called from codemode as `await tools.intercom_send({...})`, `await tools.intercom_team({})`, and so on. Every result is `{ ok, text, data }`: check `ok`, then read structured delivery flags, session lists, team roster, or pending asks from `data`. Returned errors retain this object; invalid arguments, blocked calls, and thrown exceptions can still reject. Use `try/catch` or `Promise.allSettled()` for independent operations.
+
+```javascript
+const result = await tools.intercom_send({ to: "worker", message: "Tests passed." });
+return { ok: result.ok, delivered: result.data.delivered };
+```
+
+A deferred ask has `ok: true` and `data.pending: true`; it is not a failure. Do not proceed with dependent work until the actual answer arrives. Different recipients may be asked concurrently; never create a second unresolved ask to the same recipient. Delivery means durable queue acknowledgement, not task completion.
+
+For shell notifications, use `intercom-send <session-name-or-id> <message>`. It registers an independent send-only identity and prints JSON; it does not take over the current Pi session or track replies.
+
 ## Core Patterns
 
 ### Pattern 1: Planner-Worker Delegation
@@ -78,12 +145,11 @@ Do not add artificial sleeps to form a batch. Each original message keeps its se
 
 ### Pattern 3: Find Your Manager or Team
 
-If no team exists yet, create one and have the other session join. This does not require tmux:
+For independent Pi sessions, ask for approval first, then create a task team and add the connected peer:
 
 ```typescript
-intercom_join({ name: "billing", create: true })  // manager
-intercom_join({ name: "billing" })                 // other session
-intercom_team({})
+intercom_join({ name: "billing", create: true, members: ["worker"], work: "Implement billing" })
+intercom_team({ team: "billing" })
 ```
 
 `/intercom-create billing` and `/intercom-join billing` do the same from the command line. `intercom_join({})` lists named teams and TmuxDeck workspaces without printing raw scopes.
@@ -122,7 +188,7 @@ intercom_pending({ askId: "ask-..." }) // Retrieve the full untruncated body whe
 intercom_reply({ askId: "ask-...", message: "Use exponential backoff starting at 100ms." })
 ```
 
-`intercom_reply` preserves exact threading internally. `intercom_pending` returns stable receiver-local ask IDs and short previews; models never see or construct the protocol message ID. Managers can pass `session` with an owned coworker target from `intercom_team` to inspect that coworker's pending inbox.
+`intercom_reply` preserves exact threading and the original team internally. Team-message reply hints provide an exact receiver-local `contextId`, including for ordinary messages. `intercom_pending` returns stable receiver-local ask IDs, team labels, and short previews; models never see or construct the protocol message ID. Managers can pass `session` with an owned coworker target from `intercom_team` to inspect that coworker's pending inbox.
 
 ### Pattern 5: Broadcast to Multiple Workers
 
@@ -467,7 +533,7 @@ if (result.details?.pending) {
 
 ### Session name flips or registration reports `SESSION_ID_IN_USE`
 
-The same Pi session is open in more than one live runtime, such as a desktop terminal and a mobile/RPC host. Intercom keeps the first runtime authoritative instead of allowing the two clients to evict each other. Close or switch away from the duplicate runtime; one transcript/session ID must have only one live owner.
+The same Pi session is open in more than one live runtime, such as a desktop terminal and a mobile/RPC host. Intercom keeps the first runtime authoritative instead of allowing the two clients to evict each other. The conflicting runtime pauses automatic reconnect; `intercom_status` returns `ok: false` with `data.code: "SESSION_ID_IN_USE"`. Switch to a different session, or release the duplicate owner and `/reload`. One transcript/session ID must have only one live owner; do not auto-generate a replacement identity for a running session.
 
 ### Message not delivered
 

package/tool-result.ts

@@ -0,0 +1,26 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export const intercomOutputSchema = Type.Object({
+  ok: Type.Boolean(),
+  text: Type.String(),
+  data: Type.Record(Type.String(), Type.Unknown()),
+});
+
+type ToolResult = Awaited<ReturnType<ToolDefinition<any, any>["execute"]>>;
+
+/** Keep model/TUI content unchanged while giving codemode callers JSON data. */
+export function structuredIntercomResult(result: ToolResult): ToolResult {
+  const details = result.details ?? {};
+  const isError = result.isError === true || details.error === true || details.delivered === false;
+  return {
+    ...result,
+    details,
+    isError,
+    structuredContent: {
+      ok: !isError,
+      text: result.content.filter((item) => item.type === "text").map((item) => item.text).join("\n"),
+      data: JSON.parse(JSON.stringify(details)),
+    },
+  };
+}

package/types.ts

@@ -36,6 +36,8 @@ export interface Message {
   expectsReply?: boolean;
   content: {
     text: string;
+    /** Public, immutable task-team name; not a broker registration scope. */
+    team?: string;
     attachments?: Attachment[];
     control?: IntercomCommonControlEnvelope;
   };

package/ui/inline-message.ts

@@ -47,7 +47,8 @@ export class InlineMessageComponent implements Component {
     }
     const bodyWidth = Math.max(1, width - 2);
 
-    const header = ` 📨 From: ${senderName} (${senderCwd}) `;
+    const teamLabel = this.message.content.team ? `[Team: ${sanitizeDisplayText(this.message.content.team)}] ` : "";
+    const header = ` ${teamLabel}📨 From: ${senderName} (${senderCwd}) `;
     const headerText = truncateToWidth(this.collapsed ? `${header} Ctrl+O expands ` : header, bodyWidth, "");
     const headerPadding = Math.max(0, bodyWidth - visibleWidth(headerText));
     lines.push(this.theme.fg("accent", `╭${headerText}${borderChar.repeat(headerPadding)}╮`));