@ctliz/agent-intercom-pi 0.12.0-connect.8 → 0.12.0-connect.9

package/README.md

@@ -26,7 +26,7 @@ Grok Build and AGY are supported as first-class protocol peers through two dedic
 | Grok Build | [`@ctliz/agent-intercom-grok`](https://www.npmjs.com/package/@ctliz/agent-intercom-grok) | `agent-intercom-grok-mcp` |
 | AGY | [`@ctliz/agent-intercom-agy`](https://www.npmjs.com/package/@ctliz/agent-intercom-agy) | `agent-intercom-agy-mcp` |
 
-The host packages depend on `@ctliz/agent-intercom-claude` and load its MCP runtime internally. Users do **not** need to install or place `claude-intercom-mcp` on `PATH` separately. Once connected, Grok and AGY sessions share the same local broker and protocol as Pi, Codex, Claude Code, and OpenCode, and expose all nine MCP operations: `intercom_whoami`, `intercom_list`, `intercom_send`, `intercom_ask`, `intercom_reply`, `intercom_pending`, `intercom_status`, `intercom_team`, and `intercom_set_summary`.
+The host packages depend on `@ctliz/agent-intercom-claude` and load its MCP runtime internally. Users do **not** need to install or place `claude-intercom-mcp` on `PATH` separately. Once connected, Grok and AGY sessions share the same local broker and protocol as Pi, Codex, Claude Code, and OpenCode, and expose the MCP operations: `intercom_whoami`, `intercom_list`, `intercom_send`, `intercom_ask`, `intercom_reply`, `intercom_pending`, `intercom_status`, `intercom_team`, `intercom_join`, and `intercom_set_summary`.
 
 Install the host adapter before installing its plugin:
 
@@ -93,7 +93,7 @@ Each pi session that has `pi-intercom` loaded and enabled connects to a tiny loc
 ## Install
 
 ```bash
-pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.8
+pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.9
 ```
 
 If you are coming from `connect.1`, read [Upgrading from `connect.1`](#upgrading-from-connect1-to-connect2) first — the package namespace changed and the two versions must not be installed side by side.
@@ -141,7 +141,7 @@ A session becomes intercom-connected when all of these are true:
 
 The session list only shows intercom-connected sessions, not every open Pi process on the machine.
 
-If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.8` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.5`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
+If you upgrade pi-intercom or the orchestrator while sessions are already open, run `/reload` in each open Pi session (and restart any companion `coi`, `cci`, or OpenCode adapter). Update the packages by reinstalling the exact release tags with `pi install git:github.com/ctliz/agent-intercom-pi@v0.12.0-connect.9` and, only where Orchestrator is actually installed, `pi install git:github.com/ctliz/agent-intercom-orchestrator@v0.12.0-connect.5`. Extensions are loaded into the running host process, so an existing session cannot adopt new broker/discovery code until it reloads. This is especially important when upgrading from a release that allowed multiple broker processes to form separate session-list "islands": the broker ownership fix prevents new splits, but it cannot move clients that are still running the old code. After every host has reloaded once, they converge on the same broker automatically.
 
 If `/intercom` still reports no peers, first confirm the other Pi windows have pi-intercom loaded and have also been reloaded. Open Pi processes without the extension, disabled sessions, and sessions using a different `PI_CODING_AGENT_DIR` intentionally do not appear in the same list.
 
@@ -175,7 +175,7 @@ Press **Alt+I** or run `/intercom-id` to copy a short handoff snippet for the cu
 
 ### From the Agent
 
-The agent uses seven focused tools: `intercom_send`, `intercom_ask`, `intercom_reply`, `intercom_team`, `intercom_list`, `intercom_pending`, and `intercom_status`. Tool calls and results render as compact transcript rows so coordination is easy to scan. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
+The agent uses eight focused tools: `intercom_send`, `intercom_ask`, `intercom_reply`, `intercom_team`, `intercom_join`, `intercom_list`, `intercom_pending`, and `intercom_status`. Tool calls and results render as compact transcript rows so coordination is easy to scan. For common patterns like planner-worker delegation, the bundled `pi-intercom` skill provides copy-paste ready examples:
 
 ```typescript
 // Find the manager and managed coworkers without searching the global list
@@ -297,7 +297,7 @@ If you never set `/name`, Intercom still exposes a runtime-only fallback alias s
 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.
+4. **Standalone** — no manager and no coworkers. Create a named team with `/intercom-create` or `intercom_join({ create: true })`, or use `/name` plus `intercom_list` / `intercom_send`.
 
 Typical result:
 
@@ -319,16 +319,32 @@ 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
+### Create or join a team without tmux
 
-`/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.
+Named teams live in the local Intercom directory. Creating one generates a private scope, makes this session the manager, and is enough for `intercom_team` to return a live roster. Tmux and TmuxDeck are not required.
 
 ```text
-/intercom-join                 # list joinable workspaces
-/intercom-join frontend        # join by exact workspace name
+/intercom-create billing       # create a named team and join as manager
+/intercom-join billing         # join that named team from another session
+/intercom-join                 # list named teams and TmuxDeck workspaces
 /intercom-join 1               # join by the listed number
-/intercom-join --scope <48hex> # join by the workspace scope
 /intercom-status               # confirm membership and visible peers
+intercom_team({})
+```
+
+Agents can do the same without a slash command:
+
+```typescript
+intercom_join({ name: "billing", create: true })  // create and join as manager
+intercom_join({ name: "billing" })                 // join an existing named team
+intercom_join({})                                  // list joinable teams
+```
+
+`/intercom-join` can still attach a standalone Pi session to an existing TmuxDeck workspace circle. That path 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 frontend        # join by exact TmuxDeck workspace name
+/intercom-join --scope <48hex> # join by the workspace scope
 ```
 
 Managed Team Workers and Orchestrator-owned sessions cannot join another circle. Listing never prints the raw scope.
@@ -347,7 +363,18 @@ intercom_status({})
 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`.
+`intercom_list` should now show both `planner` and `worker`. They are still standalone until one session creates a named team:
+
+```text
+# Terminal 1
+/intercom-create billing
+
+# Terminal 2
+/intercom-join billing
+intercom_team({})
+```
+
+After that, `intercom_team` returns the pair as a live roster. If these terminals were launched inside the same TmuxDeck workspace, the live roster is already present without `/intercom-create`.
 
 Planner assigns work:
 
@@ -374,7 +401,7 @@ intercom_send({
 })
 ```
 
-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:
+If a third Pi is already running as `reviewer`, join the named team from a new standalone window:
 
 ```text
 /intercom-join billing
@@ -578,6 +605,7 @@ The supervisor can reply with plain JSON or a fenced `json` block. If the reply
 | `intercom_ask` | required `to`, required `message`, optional `attachments` | Ask and wait briefly for a reply |
 | `intercom_reply` | required `message`, optional `askId`, `to`, `which` | Reply to the active or pending inbound message; `askId` selects an exact unresolved ask, while `to`/`which` remain compatible selectors |
 | `intercom_team` | none | Show the current manager and live coworkers owned by that manager |
+| `intercom_join` | optional `name`, optional `create` | List, join, or create a named team without tmux |
 | `intercom_list` | none | List connected sessions in your scope |
 | `intercom_pending` | optional `askId`, `session` | List unresolved inbound asks with stable IDs; `askId` retrieves the full untruncated body, and managers may use `session` for an owned coworker |
 | `intercom_status` | none | Show connection and queue status |
@@ -604,6 +632,8 @@ Only registered in sessions where `pi-subagents` supplied the required child bri
 
 **`intercom_team`** reads orchestrator ownership dynamically and returns the current manager plus live same-manager coworkers. After adoption it follows the new manager without restarting the worker; `AGENT_INTERCOM_MANAGER_TARGET` is only a startup fallback.
 
+**`intercom_join`** lists named teams and TmuxDeck workspaces, joins one by name, or creates a named team with `create: true`. Creating a team does not require tmux. Listing never prints the raw scope.
+
 **`intercom_list`** returns the current session plus other active intercom-connected sessions with name, short ID, working directory, model, and live status. Under protocol v4 it is same-scope: it returns only sessions sharing your scope (or only unscoped sessions when you are unscoped). Cross-scope contact is possible only by exact full session ID. Orchestrator-owned workers should still prefer `intercom_team` for their group.
 
 **`intercom_send`** sends immediately and distinguishes broker `accepted` from receiver-acknowledged `delivered`. Set `confirmSend: true` for an interactive confirmation dialog.

package/index.ts

@@ -24,7 +24,6 @@ import {
   currentTmuxWorkspace,
   formatJoinStatus,
   formatJoinSuccess,
-  formatJoinableWorkspaceList,
   isZhLocale,
   listScopedWorkspaces,
   parseJoinArgs,
@@ -32,6 +31,18 @@ import {
   rejectManagedJoin,
   workspaceNameForScope,
 } from "./workspace-join.ts";
+import {
+  buildJoinableCircles,
+  createNamedTeam,
+  findNamedTeamByScope,
+  formatCreateSuccess,
+  formatJoinableCircleList,
+  formatNamedJoinSuccess,
+  listNamedTeams,
+  parseCreateArgs,
+  parseTeamName,
+  resolveJoinCircle,
+} from "./named-teams.ts";
 import { authorizeBossSender, BossTeamScopeError, bossSelfSessionError, filterBossSessions, isBossControllerReadinessControl, readBossTeamScope, resolveBossLiveTarget } from "./boss-team-scope.ts";
 import {
   INTERCOM_CONTROL_DELIVERY_EVENT,
@@ -886,6 +897,76 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     }
     await ensureConnected("tool");
   }
+  function currentDisplayName(): string {
+    return currentSessionId
+      ? buildPresenceIdentity(pi, currentSessionId).name
+      : (pi.getSessionName()?.trim() || "unnamed");
+  }
+  function rejectCircleChange(): string | undefined {
+    if (bossTeamScope.present) {
+      return isZhLocale()
+        ? "Boss 团队模式下不能创建或加入其他团队。"
+        : "Boss team-only mode cannot create or join another team.";
+    }
+    return rejectManagedJoin(classifyMembership(), isZhLocale());
+  }
+  async function applyCircleScope(ctx: ExtensionContext, scopeId: string, managerSessionId?: string): Promise<void> {
+    if (managerSessionId) {
+      process.env.AGENT_INTERCOM_MANAGER_TARGET = managerSessionId;
+    } else {
+      delete process.env.AGENT_INTERCOM_MANAGER_TARGET;
+    }
+    if (!getLiveContext(ctx)) {
+      startSessionRuntime(ctx);
+    }
+    await switchRuntimeScope(scopeId);
+    syncPresenceIdentity(currentSessionId ?? ctx.sessionManager.getSessionId());
+  }
+  async function createAndJoinNamedTeam(ctx: ExtensionContext, name: string): Promise<string> {
+    const blocked = rejectCircleChange();
+    if (blocked) throw new Error(blocked);
+    const teamName = parseTeamName(name);
+    if (!getLiveContext(ctx)) {
+      startSessionRuntime(ctx);
+    }
+    const managerSessionId = currentSessionId ?? ctx.sessionManager.getSessionId();
+    const team = createNamedTeam({ name: teamName, managerSessionId });
+    await applyCircleScope(ctx, team.scopeId, team.managerSessionId);
+    return formatCreateSuccess({ team: team.name, name: currentDisplayName(), zh: isZhLocale() });
+  }
+  async function listOrJoinCircle(ctx: ExtensionContext, args: string): Promise<string> {
+    const zh = isZhLocale();
+    const blocked = rejectCircleChange();
+    if (blocked) throw new Error(blocked);
+    const parsed = parseJoinArgs(args);
+    const namedTeams = listNamedTeams();
+    const workspaces = await listScopedWorkspaces();
+    const circles = buildJoinableCircles({ namedTeams, workspaces });
+    if (parsed.kind === "list") {
+      return formatJoinableCircleList({ circles, zh });
+    }
+    let selected = resolveJoinCircle({ parsed, namedTeams, workspaces });
+    if (!selected && parsed.kind === "workspace" && parsed.workspace) {
+      const scope = await readSessionScope(parsed.workspace);
+      if (scope) selected = { name: parsed.workspace, kind: "tmuxdeck", scopeId: scope };
+    }
+    if (!selected && parsed.kind === "scope" && parsed.scope) {
+      const workspace = await workspaceNameForScope(parsed.scope);
+      if (workspace) {
+        const scope = await readSessionScope(workspace);
+        if (scope) selected = { name: workspace, kind: "tmuxdeck", scopeId: scope };
+      }
+    }
+    if (!selected) {
+      throw new Error(parsed.kind === "index"
+        ? (zh ? "没有这个编号的团队。" : "No team uses that number.")
+        : (zh ? "无法加入该团队。" : "Could not join that team."));
+    }
+    await applyCircleScope(ctx, selected.scopeId, selected.managerSessionId);
+    return selected.kind === "named"
+      ? formatNamedJoinSuccess({ team: selected.name, name: currentDisplayName(), zh })
+      : formatJoinSuccess({ workspace: selected.name, name: currentDisplayName(), zh });
+  }
 
   function restoreIntercomSessionId(): void {
     if (previousIntercomSessionId === undefined) {
@@ -1794,6 +1875,7 @@ export default function piIntercomExtension(pi: ExtensionAPI) {
     "intercom_pending",
     "intercom_status",
     "intercom_team",
+    "intercom_join",
     "contact_supervisor",
   ]);
 
@@ -2707,6 +2789,49 @@ Usage:
     },
   } as any);
 
+  pi.registerTool({
+    name: "intercom_join",
+    label: "Intercom Join",
+    description: "List, join, or create a named intercom team without tmux. Omit name to list joinable teams. Set create=true to create a team and join as manager.",
+    promptSnippet: "Join or create a named intercom team so intercom_team works without tmux.",
+    promptGuidelines: [
+      "Use intercom_join with no name to list named teams and TmuxDeck workspaces.",
+      "Use intercom_join({ name: \"billing\" }) to join an existing named team or workspace.",
+      "Use intercom_join({ name: \"billing\", create: true }) to create a named team and join as manager.",
+    ],
+    parameters: Type.Object({
+      name: Type.Optional(Type.String({ description: "Team name to join. Omit to list joinable teams." })),
+      create: Type.Optional(Type.Boolean({ description: "Create this named team and join as manager. Requires name." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const zh = isZhLocale();
+        if (params.create) {
+          if (typeof params.name !== "string" || !params.name.trim()) {
+            throw new Error(zh ? "创建团队需要名称。" : "Creating a team requires a name.");
+          }
+          const text = await createAndJoinNamedTeam(ctx, params.name);
+          return { content: [{ type: "text", text }] };
+        }
+        const text = await listOrJoinCircle(ctx, typeof params.name === "string" ? params.name : "");
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: getErrorMessage(error) }], details: toolErrorDetails(error) };
+      }
+    },
+    renderCall(args, theme) {
+      const name = typeof args.name === "string" && args.name.trim() ? args.name.trim() : "";
+      const suffix = args.create === true ? (name ? ` create ${name}` : " create") : (name ? ` ${name}` : "");
+      return new Text(theme.fg("toolTitle", theme.bold(`intercom_join${suffix}`)), 0, 0);
+    },
+    renderResult(result, { isPartial }, theme, context) {
+      if (isPartial) return new Text(theme.fg("warning", "Joining team..."), 0, 0);
+      const details = result.details as { error?: boolean } | undefined;
+      const failed = Boolean(context.isError || details?.error === true);
+      return new Text(`${failed ? theme.fg("error", "✗ ") : theme.fg("success", "✓ ")}${theme.fg(failed ? "error" : "text", firstTextContent(result))}`, 0, 0);
+    },
+  } as any);
+
   for (const definition of [
     { name: "intercom_list", label: "Intercom List", action: "list", description: "List active local intercom sessions.", promptSnippet: "List active local intercom sessions." },
     { name: "intercom_pending", label: "Intercom Pending", action: "pending", description: "List unresolved inbound intercom asks with stable IDs, or retrieve one ask's full body. Managers may inspect an owned coworker's inbox. This does not list questions you sent to other sessions.", promptSnippet: "List unresolved inbound asks or retrieve one full ask by its stable ID." },
@@ -2889,70 +3014,23 @@ Usage:
     },
   });
 
+  pi.registerCommand("intercom-create", {
+    description: "Create a named intercom team and join it as manager. Does not require tmux.",
+    handler: async (args, ctx) => {
+      try {
+        const name = parseCreateArgs(args);
+        notifyIfLive(ctx, await createAndJoinNamedTeam(ctx, name), "info");
+      } catch (error) {
+        notifyIfLive(ctx, getErrorMessage(error), "error");
+      }
+    },
+  });
+
   pi.registerCommand("intercom-join", {
-    description: "Join an existing TmuxDeck workspace intercom circle. This does not enroll you as a Team Worker.",
+    description: "Join a named intercom team or an existing TmuxDeck workspace circle.",
     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");
+        notifyIfLive(ctx, await listOrJoinCircle(ctx, args), "info");
       } catch (error) {
         notifyIfLive(ctx, getErrorMessage(error), "error");
       }
@@ -2965,11 +3043,11 @@ Usage:
       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");
+        const namedTeam = runtimeScopeId ? findNamedTeamByScope(runtimeScopeId) : undefined;
+        const workspace = namedTeam?.name
+          ? undefined
+          : await currentTmuxWorkspace()
+            ?? (runtimeScopeId ? await workspaceNameForScope(runtimeScopeId) : undefined);
         let peers: string[] = [];
         if (client?.isConnected()) {
           const sessions = await client.listSessions();
@@ -2980,7 +3058,8 @@ Usage:
         notifyIfLive(ctx, formatJoinStatus({
           membership,
           workspace,
-          name: displayName,
+          team: namedTeam?.name,
+          name: currentDisplayName(),
           peers,
           zh,
         }), "info");

package/named-teams.ts

@@ -0,0 +1,250 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureIntercomRuntimeDir, getAgentDirPath, getIntercomDirPath } from "./broker/paths.ts";
+import { writeDurableJson } from "./durable-json.ts";
+import { isTmuxDeckScope, isZhLocale, type ParsedJoinArgs, type ScopedWorkspace } from "./workspace-join.ts";
+
+export const NAMED_TEAMS_FILE = "named-teams.json";
+export const NAMED_TEAMS_VERSION = 1;
+export const NAMED_TEAM_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+
+export interface NamedTeam {
+  name: string;
+  scopeId: string;
+  managerSessionId: string;
+  createdAt: number;
+}
+
+export type JoinableCircleKind = "named" | "tmuxdeck";
+
+export interface JoinableCircle {
+  name: string;
+  kind: JoinableCircleKind;
+  scopeId: string;
+  managerSessionId?: string;
+}
+
+interface NamedTeamsFile {
+  version: number;
+  teams: NamedTeam[];
+}
+
+function teamsFilePath(agentDir?: string): string {
+  return join(getIntercomDirPath(agentDir ?? getAgentDirPath()), NAMED_TEAMS_FILE);
+}
+
+function genericReadError(zh: boolean): Error {
+  return new Error(zh ? "无法读取本地团队列表。" : "Could not read the local named-team list.");
+}
+
+function genericWriteError(zh: boolean): Error {
+  return new Error(zh ? "无法创建该团队。" : "Could not create that named team.");
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseStoredTeam(value: unknown): NamedTeam | undefined {
+  if (!isPlainObject(value)) return undefined;
+  if (typeof value.name !== "string" || !NAMED_TEAM_NAME_PATTERN.test(value.name)) return undefined;
+  if (typeof value.scopeId !== "string" || !isTmuxDeckScope(value.scopeId)) return undefined;
+  if (typeof value.managerSessionId !== "string" || !value.managerSessionId.trim()) return undefined;
+  if (value.managerSessionId !== value.managerSessionId.trim() || /[\u0000-\u001f\u007f]/.test(value.managerSessionId)) {
+    return undefined;
+  }
+  if (typeof value.createdAt !== "number" || !Number.isSafeInteger(value.createdAt) || value.createdAt <= 0) {
+    return undefined;
+  }
+  return {
+    name: value.name,
+    scopeId: value.scopeId,
+    managerSessionId: value.managerSessionId,
+    createdAt: value.createdAt,
+  };
+}
+
+export function parseTeamName(raw: string, zh: boolean = isZhLocale()): string {
+  const name = raw.trim();
+  if (!name || name.includes(" ") || !NAMED_TEAM_NAME_PATTERN.test(name)) {
+    throw new Error(zh
+      ? "用法：/intercom-create <名称>\n团队名需以字母开头，只能包含字母、数字、连字符或下划线（最长 32）。"
+      : "Usage: /intercom-create <name>\nTeam names start with a letter and may include letters, numbers, hyphens, or underscores (max 32).");
+  }
+  return name;
+}
+
+export function parseCreateArgs(raw: string, zh: boolean = isZhLocale()): string {
+  const args = raw.trim().split(/\s+/).filter(Boolean);
+  if (args.length !== 1) {
+    throw new Error(zh
+      ? "用法：/intercom-create <名称>"
+      : "Usage: /intercom-create <name>");
+  }
+  return parseTeamName(args[0]!, zh);
+}
+
+export function generateNamedTeamScope(existing: Iterable<string> = []): string {
+  const taken = new Set(existing);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const scopeId = randomBytes(24).toString("hex");
+    if (!taken.has(scopeId)) return scopeId;
+  }
+  throw genericWriteError(isZhLocale());
+}
+
+export function listNamedTeams(agentDir?: string): NamedTeam[] {
+  const zh = isZhLocale();
+  let raw: string;
+  try {
+    raw = readFileSync(teamsFilePath(agentDir), "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw genericReadError(zh);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw genericReadError(zh);
+  }
+  if (!isPlainObject(parsed) || parsed.version !== NAMED_TEAMS_VERSION || !Array.isArray(parsed.teams)) {
+    throw genericReadError(zh);
+  }
+
+  const teams: NamedTeam[] = [];
+  const names = new Set<string>();
+  const scopes = new Set<string>();
+  for (const entry of parsed.teams) {
+    const team = parseStoredTeam(entry);
+    if (!team || names.has(team.name) || scopes.has(team.scopeId)) {
+      throw genericReadError(zh);
+    }
+    names.add(team.name);
+    scopes.add(team.scopeId);
+    teams.push(team);
+  }
+  return teams;
+}
+
+export function findNamedTeam(name: string, agentDir?: string): NamedTeam | undefined {
+  return listNamedTeams(agentDir).find((team) => team.name === name);
+}
+
+export function findNamedTeamByScope(scopeId: string, agentDir?: string): NamedTeam | undefined {
+  return listNamedTeams(agentDir).find((team) => team.scopeId === scopeId);
+}
+
+export function createNamedTeam(input: {
+  name: string;
+  managerSessionId: string;
+  agentDir?: string;
+  now?: number;
+  generateScope?: () => string;
+}): NamedTeam {
+  const zh = isZhLocale();
+  const name = parseTeamName(input.name, zh);
+  const managerSessionId = input.managerSessionId.trim();
+  if (!managerSessionId || managerSessionId !== input.managerSessionId || /[\u0000-\u001f\u007f]/.test(managerSessionId)) {
+    throw genericWriteError(zh);
+  }
+
+  const existing = listNamedTeams(input.agentDir);
+  if (existing.some((team) => team.name === name)) {
+    throw new Error(zh
+      ? `团队 ${name} 已存在。`
+      : `A named team called ${name} already exists.`);
+  }
+
+  const scopeId = (input.generateScope ?? (() => generateNamedTeamScope(existing.map((team) => team.scopeId))))();
+  if (!isTmuxDeckScope(scopeId) || existing.some((team) => team.scopeId === scopeId)) {
+    throw genericWriteError(zh);
+  }
+
+  const team: NamedTeam = {
+    name,
+    scopeId,
+    managerSessionId,
+    createdAt: input.now ?? Date.now(),
+  };
+  const dir = getIntercomDirPath(input.agentDir ?? getAgentDirPath());
+  ensureIntercomRuntimeDir(dir);
+  const payload: NamedTeamsFile = { version: NAMED_TEAMS_VERSION, teams: [...existing, team] };
+  writeDurableJson(teamsFilePath(input.agentDir), payload);
+  return team;
+}
+
+export function buildJoinableCircles(input: {
+  namedTeams: NamedTeam[];
+  workspaces: ScopedWorkspace[];
+}): JoinableCircle[] {
+  return [
+    ...input.namedTeams.map((team) => ({
+      name: team.name,
+      kind: "named" as const,
+      scopeId: team.scopeId,
+      managerSessionId: team.managerSessionId,
+    })),
+    ...input.workspaces.map((workspace) => ({
+      name: workspace.sessionName,
+      kind: "tmuxdeck" as const,
+      scopeId: workspace.scopeId,
+    })),
+  ];
+}
+
+export function resolveJoinCircle(input: {
+  parsed: ParsedJoinArgs;
+  namedTeams: NamedTeam[];
+  workspaces: ScopedWorkspace[];
+}): JoinableCircle | undefined {
+  const circles = buildJoinableCircles(input);
+  if (input.parsed.kind === "list") return undefined;
+  if (input.parsed.kind === "index") {
+    return input.parsed.index ? circles[input.parsed.index - 1] : undefined;
+  }
+  if (input.parsed.kind === "workspace" && input.parsed.workspace) {
+    return circles.find((circle) => circle.name === input.parsed.workspace);
+  }
+  if (input.parsed.kind === "scope" && input.parsed.scope) {
+    return circles.find((circle) => circle.scopeId === input.parsed.scope);
+  }
+  return undefined;
+}
+
+export function formatJoinableCircleList(input: {
+  circles: Array<Pick<JoinableCircle, "name" | "kind">>;
+  zh: boolean;
+}): string {
+  if (input.circles.length === 0) {
+    return input.zh
+      ? "没有可加入的团队。\n使用 /intercom-create <名称> 创建一个。"
+      : "No joinable teams found.\nCreate one with /intercom-create <name>.";
+  }
+  const header = input.zh ? "可加入的通话团队：" : "Joinable intercom teams:";
+  const footer = input.zh ? "请输入编号或精确名称：" : "Select a team by number or exact name:";
+  return [
+    header,
+    ...input.circles.map((circle, index) => {
+      const suffix = circle.kind === "tmuxdeck" ? " (TmuxDeck)" : "";
+      return `  ${index + 1}) ${circle.name}${suffix}`;
+    }),
+    footer,
+  ].join("\n");
+}
+
+export function formatCreateSuccess(input: { team: string; name: string; zh: boolean }): string {
+  return input.zh
+    ? `已创建团队 ${input.team}，并以管理者身份加入。\n你的显示名：${input.name}`
+    : `Created team ${input.team} and joined as manager.\nDisplay name: ${input.name}`;
+}
+
+export function formatNamedJoinSuccess(input: { team: string; name: string; zh: boolean }): string {
+  return input.zh
+    ? `已加入团队 ${input.team}。\n身份：团队成员\n你的显示名：${input.name}`
+    : `Joined team ${input.team}.\nRole: teammate\nDisplay name: ${input.name}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctliz/agent-intercom-pi",
-  "version": "0.12.0-connect.8",
+  "version": "0.12.0-connect.9",
   "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",

package/skills/pi-intercom/SKILL.md

@@ -78,6 +78,16 @@ 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:
+
+```typescript
+intercom_join({ name: "billing", create: true })  // manager
+intercom_join({ name: "billing" })                 // other session
+intercom_team({})
+```
+
+`/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.
+
 Orchestrator-owned coworkers should use the no-argument team tool instead of searching the global peer list:
 
 ```typescript
@@ -210,7 +220,7 @@ intercom_reply({ askId: "ask-...", message: "Use the v2 API." })
 
 **Important:** Only sessions where `pi-subagents` supplied child bridge metadata
 get the `contact_supervisor` tool. Normal sessions use the split `intercom_send`,
-`intercom_ask`, `intercom_reply`, `intercom_team`, `intercom_list`, `intercom_pending`, and
+`intercom_ask`, `intercom_reply`, `intercom_team`, `intercom_join`, `intercom_list`, `intercom_pending`, and
 `intercom_status` tools. If you see the formatted supervisor decision/progress update message, treat
 it as a `contact_supervisor` escalation.
 
@@ -222,6 +232,7 @@ it as a `contact_supervisor` escalation.
 | `ask` | Waits up to 30 seconds, then continues asynchronously | You need an answer but should not hold the agent indefinitely |
 | `reply` | Responds to the active or pending inbound ask | You were asked something and need to answer naturally |
 | `pending` | Lists unresolved inbound asks | You need to see who is waiting before replying |
+| `join` | Lists, joins, or creates a named team | You need a team without tmux |
 | `list` | Returns all sessions with live status | You need to discover targets or choose an idle peer |
 | `status` | Returns your connection state | Troubleshooting |
 
@@ -397,14 +408,15 @@ Use `/name` so others can target you easily:
 /name planner
 ```
 
-To join an existing TmuxDeck workspace intercom circle without becoming a Team Worker:
+To form a team without tmux:
 
 ```
-/intercom-join frontend
+/intercom-create billing
+/intercom-join billing
 /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.
+Agents can use `intercom_join({ name: "billing", create: true })` or `intercom_join({ name: "billing" })`. `/intercom-join` with no argument lists named teams and TmuxDeck workspaces. Joining a TmuxDeck workspace is same-scope messaging only; it does not enroll you as a Team Worker.
 
 ## Error Handling
 

package/workspace-join.ts

@@ -50,8 +50,8 @@ export function parseJoinArgs(raw: string): ParsedJoinArgs {
   }
   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>");
+      ? "用法：/intercom-join [团队名或编号] 或 /intercom-join --scope <48 hex>"
+      : "Usage: /intercom-join [team or number] or /intercom-join --scope <48 hex>");
   }
   if (/^[1-9]\d*$/.test(args[0])) {
     return { kind: "index", index: Number(args[0]) };
@@ -206,20 +206,24 @@ export function formatJoinSuccess(input: { workspace: string; name: string; zh:
 export function formatJoinStatus(input: {
   membership: JoinMembership;
   workspace?: string;
+  team?: string;
   name: string;
   peers: string[];
   zh: boolean;
 }): string {
+  const circle = input.zh
+    ? (input.team ? `团队：${input.team}` : `工作区：${input.workspace || "无"}`)
+    : (input.team ? `Team: ${input.team}` : `Workspace: ${input.workspace || "none"}`);
   return input.zh
     ? [
       input.membership,
-      `工作区：${input.workspace || "无"}`,
+      circle,
       `显示名：${input.name}`,
       `同圈可见：${input.peers.length > 0 ? input.peers.join(", ") : "无"}`,
     ].join("\n")
     : [
       input.membership,
-      `Workspace: ${input.workspace || "none"}`,
+      circle,
       `Display name: ${input.name}`,
       `Visible in circle: ${input.peers.length > 0 ? input.peers.join(", ") : "none"}`,
     ].join("\n");