@ctliz/agent-intercom-pi 0.12.0-connect.1 → 0.12.0-connect.3

package/README.md

@@ -218,6 +218,139 @@ Sender identity in `intercom:control.from.id` comes from the broker delivery fra
 
 The control bus is intentionally not exposed as a model-facing generic Intercom tool. Companion extensions expose only their specific, reviewed actions.
 
+## Teams, names, and who can talk to whom
+
+A **team** in Agent Intercom is the small group a session should treat as coworkers. It is not the same as the machine-wide session list. Agents that belong to a team should start with `intercom_team({})` and only fall back to `intercom_list({})` when they need an independently launched peer.
+
+`/name` is how a human gives a session a stable, speakable handle. The broker still identifies every session by a stable session ID; the name is the convenient address other agents should use when it is unique.
+
+### Name a session with `/name`
+
+`/name` is a Pi host command, not an Intercom command. After you set it, Intercom republishes the new name so other connected sessions can target it.
+
+```text
+# Terminal 1
+/name planner
+
+# Terminal 2
+/name worker
+
+# Terminal 3
+/name reviewer
+```
+
+Good names are short, unique in the same scope, and describe the role: `planner`, `api-worker`, `frontend-dev`. Avoid spaces. If two live sessions share the same name, prefer the short ID shown by `intercom_list` or the exact full session ID from `/intercom-id`.
+
+Check the published name:
+
+```typescript
+intercom_status({})
+intercom_list({})
+```
+
+Copy a host-neutral contact snippet for another agent:
+
+```text
+/intercom-id
+```
+
+That snippet uses the unique name when possible and falls back to the stable session ID when names collide.
+
+If you never set `/name`, Intercom still exposes a runtime-only fallback alias such as `subagent-chat-1a2b3c4d` so peers can reach the session. That alias is not stored as the Pi session title.
+
+### How `intercom_team` chooses a team
+
+`intercom_team({})` has no arguments. It resolves the current group in this order and stops at the first match:
+
+1. **Orchestrator** — `~/.pi/agent/intercom/orchestrator/workers.json` has an owned record for this session (`AGENT_INTERCOM_WORKER_ID`) or this session is the current manager of live owned coworkers.
+2. **TmuxDeck manifest** — `AGENT_INTERCOM_TEAM_MANIFEST` points at a valid team file. The Lead is `leadId`; workers are the other members. An invalid or empty manifest fails closed and does not fall through to the live roster.
+3. **Same-scope live roster** — `AGENT_INTERCOM_SCOPE_ID` is set. Coworkers are the other live non-human sessions in that scope. `AGENT_INTERCOM_MANAGER_TARGET` / `AGENT_INTERCOM_MANAGER_SESSION_ID` name the Lead when present.
+4. **Standalone** — no manager and no coworkers. Use `/name` plus `intercom_list` / `intercom_send` instead.
+
+Typical result:
+
+```text
+Manager: planner [connected]
+You: worker
+Coworkers:
+- reviewer target=reviewer (pi, worker, running) [connected]
+```
+
+Use the returned `target` with `intercom_send` and `intercom_ask`. After Orchestrator adoption, the manager target updates without restarting the worker. `AGENT_INTERCOM_MANAGER_TARGET` is only a startup fallback.
+
+Only an Orchestrator manager may inspect another session's pending inbox, and only with an exact connected coworker `target` from `intercom_team`:
+
+```typescript
+intercom_team({})
+intercom_pending({ session: "tmuxdeck-11111111-2222-4333-8444-555555555555" })
+```
+
+Manifest, live-roster, and standalone teams cannot inspect another session's inbox.
+
+### Join a TmuxDeck circle without becoming a Team Worker
+
+`/intercom-join` puts a standalone Pi session into an existing TmuxDeck workspace intercom circle. It is same-scope messaging only. It does **not** write a team manifest, does **not** enroll you as a Team Worker, and does **not** grant inbox inspection.
+
+```text
+/intercom-join                 # list joinable workspaces
+/intercom-join frontend        # join by exact workspace name
+/intercom-join 1               # join by the listed number
+/intercom-join --scope <48hex> # join by the workspace scope
+/intercom-status               # confirm membership and visible peers
+```
+
+Managed Team Workers and Orchestrator-owned sessions cannot join another circle. Listing never prints the raw scope.
+
+### Example: two-person billing team
+
+Open two terminals in the same repo and start Pi in each.
+
+```text
+# Terminal 1 — the person holding the plan
+/name planner
+intercom_status({})
+
+# Terminal 2 — the person making the change
+/name worker
+intercom_list({})
+```
+
+`intercom_list` should now show both `planner` and `worker`. If these terminals were launched inside the same TmuxDeck workspace, `intercom_team` also returns that pair as a live roster. Otherwise they are standalone peers that address each other by `/name`.
+
+Planner assigns work:
+
+```typescript
+intercom_send({
+  to: "worker",
+  message: "Add idempotent refund retries in src/billing/refunds.ts. Ask before changing the public error shape."
+})
+```
+
+Worker asks a blocking question, then reports done with `send`:
+
+```typescript
+intercom_ask({
+  to: "planner",
+  message: "Refunds currently return 500 on a mid-flight timeout. Should I map that to 409 Conflict?"
+})
+// planner replies in the triggered turn:
+intercom_reply({ message: "Yes. Keep the existing error body; only change the status code." })
+
+intercom_send({
+  to: "planner",
+  message: "Done. Timeouts now return 409. Tests in refunds.test.ts pass."
+})
+```
+
+If a third Pi is already running as `reviewer` in the same TmuxDeck workspace, join from a new standalone window without becoming a Team Worker:
+
+```text
+/intercom-join billing
+/name reviewer
+intercom_team({})
+intercom_send({ to: "planner", message: "I can review the refund retry once worker is done." })
+```
+
 ## Workflow: Planner-Worker Coordination
 
 The most natural use of pi-intercom is splitting a task between two sessions — one holds the big picture, the other does the hands-on work. When the worker hits an ambiguity ("should I optimize for readability or performance here?"), they ask without losing context.

package/broker/spawn.ts

@@ -173,6 +173,7 @@ export function getBrokerSpawnOptions(
   cwd: string;
   env: NodeJS.ProcessEnv;
   windowsHide: true;
+  shell: false;
 } {
   return {
     detached: true,
@@ -180,6 +181,7 @@ export function getBrokerSpawnOptions(
     cwd: extensionDir,
     env: { ...env, PI_CODING_AGENT_DIR: getAgentDirPath(env), NODE_NO_WARNINGS: "1" },
     windowsHide: true,
+    shell: false,
   };
 }
 

package/index.ts

@@ -7,7 +7,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { IntercomClient, type SendResult } from "./broker/client.ts";
 import { parseBossControl } from "./broker/boss-adapter.ts";
 import { spawnBrokerIfNeeded } from "./broker/spawn.ts";
-import { intercomScopeIdFromEnvForRegistration } from "./protocol-v4/contract.ts";
+import { INTERCOM_SCOPE_ENV, intercomScopeIdFromEnvForRegistration } from "./protocol-v4/contract.ts";
 import { SessionListOverlay } from "./ui/session-list.ts";
 import { ComposeOverlay, type ComposeResult } from "./ui/compose.ts";
 import { InlineMessageComponent } from "./ui/inline-message.ts";
@@ -19,6 +19,19 @@ import { pendingAskId, ReplyTracker, type IntercomContext } from "./reply-tracke
 import { InboundMessageConflictError, PersistentInboundInbox, readPendingAsksSnapshot, type StoredInboundMessage } from "./inbound-inbox.ts";
 import { PersistentOutboundOutbox } from "./outbound-outbox.ts";
 import { formatIntercomTeam, resolveBossIntercomTeam, resolveIntercomTeam, resolveManagedInboxSession } from "./team.ts";
+import {
+  classifyMembership,
+  currentTmuxWorkspace,
+  formatJoinStatus,
+  formatJoinSuccess,
+  formatJoinableWorkspaceList,
+  isZhLocale,
+  listScopedWorkspaces,
+  parseJoinArgs,
+  readSessionScope,
+  rejectManagedJoin,
+  workspaceNameForScope,
+} from "./workspace-join.ts";
 import { authorizeBossSender, BossTeamScopeError, bossSelfSessionError, filterBossSessions, isBossControllerReadinessControl, readBossTeamScope, resolveBossLiveTarget } from "./boss-team-scope.ts";
 import {
   INTERCOM_CONTROL_DELIVERY_EVENT,
@@ -591,11 +604,11 @@ interface ClipboardCopyResult {
 }
 
 function runDetachedClipboardCommand(command: string, args: string[], text: string): ClipboardCopyResult {
-  const found = spawnSync("which", [command], { stdio: "ignore", timeout: 1000 });
+  const found = spawnSync("which", [command], { stdio: "ignore", timeout: 1000, shell: false });
   if (found.status !== 0) return { ok: false, error: `${command} not found` };
 
   try {
-    const proc = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"] });
+    const proc = spawn(command, args, { stdio: ["pipe", "ignore", "ignore"], shell: false });
     proc.stdin.on("error", () => {
       // Ignore EPIPE if the clipboard helper exits early.
     });
@@ -616,6 +629,7 @@ function runClipboardCommand(command: string, args: string[], text: string): Cli
     encoding: "utf8",
     timeout: 2000,
     stdio: ["pipe", "ignore", "pipe"],
+    shell: false,
   });
   if (result.status === 0) return { ok: true, method: command };
   if (result.error) return { ok: false, error: result.error.message };
@@ -655,7 +669,7 @@ function getNamePollMs(): number {
   return 1000;
 }
 export default function piIntercomExtension(pi: ExtensionAPI) {
-  const runtimeScopeId = intercomScopeIdFromEnvForRegistration();
+  let runtimeScopeId = intercomScopeIdFromEnvForRegistration();
   const initialHarnessSessionId = process.env[INTERCOM_SESSION_ID_ENV]?.trim();
   const initialGenericSessionId = process.env.AGENT_INTERCOM_SESSION_ID?.trim();
   if (initialGenericSessionId && !initialHarnessSessionId) {
@@ -859,6 +873,20 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
   function publishIntercomSessionId(sessionId: string): void {
     process.env[INTERCOM_SESSION_ID_ENV] = sessionId;
   }
+  async function switchRuntimeScope(nextScopeId: string): Promise<void> {
+    if (runtimeScopeId === nextScopeId && process.env[INTERCOM_SCOPE_ENV] === nextScopeId) {
+      return;
+    }
+    runtimeScopeId = nextScopeId;
+    process.env[INTERCOM_SCOPE_ENV] = nextScopeId;
+    const previousClient = client;
+    client = null;
+    if (previousClient) {
+      await previousClient.disconnect(true).catch(() => undefined);
+    }
+    await ensureConnected("tool");
+  }
+
   function restoreIntercomSessionId(): void {
     if (previousIntercomSessionId === undefined) {
       delete process.env[INTERCOM_SESSION_ID_ENV];
@@ -2861,6 +2889,107 @@ Usage:
     },
   });
 
+  pi.registerCommand("intercom-join", {
+    description: "Join an existing TmuxDeck workspace intercom circle. This does not enroll you as a Team Worker.",
+    handler: async (args, ctx) => {
+      const zh = isZhLocale();
+      const fail = (workspace?: string) => {
+        notifyIfLive(ctx, workspace
+          ? (zh
+            ? `无法加入工作区 ${workspace} 的通话圈。`
+            : `Could not join the intercom circle for workspace ${workspace}.`)
+          : (zh ? "无法加入该工作区通话圈。" : "Could not join that workspace intercom circle."), "error");
+      };
+      try {
+        const blocked = rejectManagedJoin(classifyMembership(), zh);
+        if (blocked) {
+          notifyIfLive(ctx, blocked, "error");
+          return;
+        }
+        const parsed = parseJoinArgs(args);
+        const workspaces = await listScopedWorkspaces();
+        let workspace: string | undefined;
+        if (parsed.kind === "list") {
+          notifyIfLive(ctx, formatJoinableWorkspaceList({ workspaces, zh }), "info");
+          return;
+        }
+        if (parsed.kind === "index" && parsed.index) {
+          const selected = workspaces[parsed.index - 1];
+          if (!selected) {
+            notifyIfLive(ctx, zh
+              ? "没有这个编号的工作区。"
+              : "No workspace uses that number.", "error");
+            return;
+          }
+          workspace = selected.sessionName;
+        } else if (parsed.kind === "workspace" && parsed.workspace) {
+          workspace = parsed.workspace;
+        } else if (parsed.kind === "scope" && parsed.scope) {
+          workspace = await workspaceNameForScope(parsed.scope);
+          if (!workspace) {
+            fail();
+            return;
+          }
+        }
+        if (!workspace) {
+          fail();
+          return;
+        }
+        const scope = await readSessionScope(workspace);
+        if (!scope) {
+          fail(workspace);
+          return;
+        }
+        if (!getLiveContext(ctx)) {
+          startSessionRuntime(ctx);
+        }
+        await switchRuntimeScope(scope);
+        syncPresenceIdentity(currentSessionId ?? ctx.sessionManager.getSessionId());
+        const displayName = currentSessionId
+          ? buildPresenceIdentity(pi, currentSessionId).name
+          : (pi.getSessionName()?.trim() || "unnamed");
+        notifyIfLive(ctx, formatJoinSuccess({
+          workspace,
+          name: displayName,
+          zh,
+        }), "info");
+      } catch (error) {
+        notifyIfLive(ctx, getErrorMessage(error), "error");
+      }
+    },
+  });
+
+  pi.registerCommand("intercom-status", {
+    description: "Show whether this session is standalone, same-scope, tmuxdeck-team, or orchestrator.",
+    handler: async (_args, ctx) => {
+      const zh = isZhLocale();
+      try {
+        const membership = classifyMembership();
+        const workspace = await currentTmuxWorkspace()
+          ?? (runtimeScopeId ? await workspaceNameForScope(runtimeScopeId) : undefined);
+        const displayName = currentSessionId
+          ? buildPresenceIdentity(pi, currentSessionId).name
+          : (pi.getSessionName()?.trim() || "unnamed");
+        let peers: string[] = [];
+        if (client?.isConnected()) {
+          const sessions = await client.listSessions();
+          peers = sessions
+            .filter((session) => session.id !== client?.sessionId && session.model !== "human")
+            .map((session) => session.name || session.id);
+        }
+        notifyIfLive(ctx, formatJoinStatus({
+          membership,
+          workspace,
+          name: displayName,
+          peers,
+          zh,
+        }), "info");
+      } catch (error) {
+        notifyIfLive(ctx, getErrorMessage(error), "error");
+      }
+    },
+  });
+
   pi.registerShortcut("alt+m", {
     description: "Open session intercom",
     handler: async (ctx) => openIntercomOverlay(ctx),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.12.0-connect.1",
+  "version": "0.12.0-connect.3",
   "license": "AGPL-3.0-or-later",
   "type": "module",
   "main": "index.ts",

package/skills/pi-intercom/SKILL.md

@@ -397,6 +397,15 @@ Use `/name` so others can target you easily:
 /name planner
 ```
 
+To join an existing TmuxDeck workspace intercom circle without becoming a Team Worker:
+
+```
+/intercom-join frontend
+/intercom-status
+```
+
+`/intercom-join` with no argument lists available TmuxDeck workspaces. Joining is same-scope messaging only; it does not enroll you as a Team Worker.
+
 ## Error Handling
 
 ### Common Errors and Solutions

package/workspace-join.ts

@@ -0,0 +1,235 @@
+import { execFile } from "node:child_process";
+import { INTERCOM_SCOPE_ENV } from "./protocol-v4/contract.ts";
+
+export type JoinMembership = "standalone" | "same-scope" | "tmuxdeck-team" | "orchestrator";
+
+export type ScopedWorkspace = {
+  sessionName: string;
+  scopeId: string;
+};
+
+export type TmuxExec = (
+  args: string[],
+  env?: NodeJS.ProcessEnv,
+) => Promise<{ ok: boolean; stdout: string }>;
+
+export interface ParsedJoinArgs {
+  kind: "list" | "workspace" | "index" | "scope";
+  workspace?: string;
+  index?: number;
+  scope?: string;
+}
+
+export function isTmuxDeckScope(value: string): boolean {
+  if (value.length !== 48) return false;
+  for (const char of value) {
+    if (!((char >= "0" && char <= "9") || (char >= "a" && char <= "f"))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function isZhLocale(env: NodeJS.ProcessEnv = process.env): boolean {
+  const locale = `${env.LC_ALL || env.LC_MESSAGES || env.LANG || ""}`.toLowerCase();
+  return locale.startsWith("zh");
+}
+
+export function parseJoinArgs(raw: string): ParsedJoinArgs {
+  const args = raw.trim().split(/\s+/).filter(Boolean);
+  if (args.length === 0) {
+    return { kind: "list" };
+  }
+  if (args[0] === "--scope") {
+    if (args.length !== 2 || !args[1]) {
+      throw new Error(isZhLocale()
+        ? "用法：/intercom-join --scope <48 hex>"
+        : "Usage: /intercom-join --scope <48 hex>");
+    }
+    return { kind: "scope", scope: parseJoinScope(args[1]) };
+  }
+  if (args.length !== 1 || args[0].startsWith("-")) {
+    throw new Error(isZhLocale()
+      ? "用法：/intercom-join [工作区名或编号] 或 /intercom-join --scope <48 hex>"
+      : "Usage: /intercom-join [workspace or number] or /intercom-join --scope <48 hex>");
+  }
+  if (/^[1-9]\d*$/.test(args[0])) {
+    return { kind: "index", index: Number(args[0]) };
+  }
+  return { kind: "workspace", workspace: args[0] };
+}
+
+export function parseJoinScope(value: string): string {
+  if (!isTmuxDeckScope(value)) {
+    throw new Error(isZhLocale()
+      ? "无法加入该工作区通话圈。"
+      : "Could not join that workspace intercom circle.");
+  }
+  return value;
+}
+
+export function classifyMembership(env: NodeJS.ProcessEnv = process.env): JoinMembership {
+  if (env.AGENT_INTERCOM_WORKER_ID?.trim() || env.AGENT_INTERCOM_OWNED === "1") {
+    return "orchestrator";
+  }
+  if (env.AGENT_INTERCOM_TEAM_MANIFEST?.trim()) {
+    return "tmuxdeck-team";
+  }
+  if (env.AGENT_INTERCOM_SCOPE_ID?.trim()) {
+    return "same-scope";
+  }
+  return "standalone";
+}
+
+export function parseTmuxEnvironmentStdout(stdout: string, varName = INTERCOM_SCOPE_ENV): string | undefined {
+  const unsetMarker = `-${varName}`;
+  const prefix = `${varName}=`;
+  for (const line of stdout.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === unsetMarker) {
+      return undefined;
+    }
+    if (trimmed.startsWith(prefix)) {
+      const value = trimmed.slice(prefix.length).trim();
+      return value || undefined;
+    }
+  }
+  return undefined;
+}
+
+export function defaultExecTmux(args: string[], env: NodeJS.ProcessEnv = process.env): Promise<{ ok: boolean; stdout: string }> {
+  return new Promise((resolve) => {
+    execFile("tmux", args, { encoding: "utf8", timeout: 2000, env, shell: false }, (error, stdout) => {
+      if (error) {
+        resolve({ ok: false, stdout: "" });
+        return;
+      }
+      resolve({ ok: true, stdout: stdout ?? "" });
+    });
+  });
+}
+
+export const tmuxRuntime = {
+  exec: defaultExecTmux as TmuxExec,
+};
+
+export async function listScopedWorkspaces(options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<ScopedWorkspace[]> {
+  const env = options.env ?? process.env;
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const listed = await execTmux(["list-sessions", "-F", "#{session_name}"], env);
+  if (!listed.ok) {
+    return [];
+  }
+  const names = listed.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const workspaces: ScopedWorkspace[] = [];
+  for (const sessionName of names) {
+    const scopeId = await readSessionScope(sessionName, { env, execTmux });
+    if (scopeId) {
+      workspaces.push({ sessionName, scopeId });
+    }
+  }
+  return workspaces;
+}
+
+export async function readSessionScope(sessionName: string, options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  const env = options.env ?? process.env;
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const shown = await execTmux(["show-environment", "-t", sessionName, INTERCOM_SCOPE_ENV], env);
+  if (!shown.ok) {
+    return undefined;
+  }
+  const raw = parseTmuxEnvironmentStdout(shown.stdout);
+  if (!raw || !isTmuxDeckScope(raw)) {
+    return undefined;
+  }
+  return raw;
+}
+
+export async function workspaceNameForScope(scope: string, options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  for (const workspace of await listScopedWorkspaces(options)) {
+    if (workspace.scopeId === scope) {
+      return workspace.sessionName;
+    }
+  }
+  return undefined;
+}
+
+export async function currentTmuxWorkspace(options: {
+  env?: NodeJS.ProcessEnv;
+  execTmux?: TmuxExec;
+} = {}): Promise<string | undefined> {
+  const env = options.env ?? process.env;
+  if (!env.TMUX?.trim()) {
+    return undefined;
+  }
+  const execTmux = options.execTmux ?? tmuxRuntime.exec;
+  const shown = await execTmux(["display-message", "-p", "#S"], env);
+  const name = shown.stdout.trim();
+  return name || undefined;
+}
+
+export function formatJoinableWorkspaceList(input: {
+  workspaces: Array<{ sessionName: string }>;
+  zh: boolean;
+}): string {
+  if (input.workspaces.length === 0) {
+    return input.zh
+      ? "没有找到带通话圈的 TmuxDeck 工作区。"
+      : "No scoped TmuxDeck workspaces found.";
+  }
+  const header = input.zh ? "可加入的 TmuxDeck 工作区：" : "Available TmuxDeck workspaces:";
+  const footer = input.zh
+    ? "请输入编号或精确工作区名（Ctrl-C 取消）："
+    : "Select a workspace by number or exact name (Ctrl-C to cancel):";
+  return [
+    header,
+    ...input.workspaces.map((workspace, index) => `  ${index + 1}) ${workspace.sessionName}`),
+    footer,
+  ].join("\n");
+}
+
+export function formatJoinSuccess(input: { workspace: string; name: string; zh: boolean }): string {
+  return input.zh
+    ? `已加入工作区 ${input.workspace} 的通话圈。\n身份：外部协作者（不是 Team Worker）\n你的显示名：${input.name}`
+    : `Joined the intercom circle for workspace ${input.workspace}.\nRole: external collaborator (not a Team Worker)\nDisplay name: ${input.name}`;
+}
+
+export function formatJoinStatus(input: {
+  membership: JoinMembership;
+  workspace?: string;
+  name: string;
+  peers: string[];
+  zh: boolean;
+}): string {
+  return input.zh
+    ? [
+      input.membership,
+      `工作区：${input.workspace || "无"}`,
+      `显示名：${input.name}`,
+      `同圈可见：${input.peers.length > 0 ? input.peers.join(", ") : "无"}`,
+    ].join("\n")
+    : [
+      input.membership,
+      `Workspace: ${input.workspace || "none"}`,
+      `Display name: ${input.name}`,
+      `Visible in circle: ${input.peers.length > 0 ? input.peers.join(", ") : "none"}`,
+    ].join("\n");
+}
+
+export function rejectManagedJoin(membership: JoinMembership, zh: boolean): string | undefined {
+  if (membership === "tmuxdeck-team" || membership === "orchestrator") {
+    return zh
+      ? "当前会话已是正式成员，不能再加入其他工作区通话圈。"
+      : "This session is already a managed member and cannot join another workspace circle.";
+  }
+  return undefined;
+}