@ctliz/agent-intercom-codex 0.12.1 → 0.13.0

package/codex/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 agent 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/codex/named-teams.ts

@@ -13,6 +13,8 @@ export interface NamedTeam {
   scopeId: string;
   managerSessionId: string;
   createdAt: number;
+  memberSessionIds?: string[];
+  work?: string;
 }
 
 interface NamedTeamsFile {
@@ -55,11 +57,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/codex/reply-context.ts

@@ -0,0 +1,49 @@
+import type { PendingInboundMessage, ReplyWhich } from "./runtime.ts";
+import { selectPendingAsk } from "./runtime.ts";
+
+export function contextId(entry: PendingInboundMessage): string {
+  return `ctx-${entry.message.id}`;
+}
+
+export function askId(entry: PendingInboundMessage): string {
+  return `ask-${entry.message.id}`;
+}
+
+export function replyHint(entry: PendingInboundMessage): string {
+  const team = entry.message.content.team;
+  return `${team ? ` [Team: ${team}]` : ""} [contextId: ${contextId(entry)}]${entry.message.expectsReply ? ` [askId: ${askId(entry)}]` : ""}`;
+}
+
+/** Select from the receiver's own retained inbox, never from a mutable current team. */
+export function selectReplyContext(entries: PendingInboundMessage[], asks: PendingInboundMessage[], input: {
+  to?: string;
+  which?: ReplyWhich;
+  askId?: string;
+  contextId?: string;
+  team?: string;
+}): PendingInboundMessage {
+  if (input.askId && input.contextId) throw new Error("Specify askId or contextId, not both");
+  let target: PendingInboundMessage;
+  if (input.askId || input.contextId) {
+    const selected = input.askId
+      ? asks.find((entry) => askId(entry) === input.askId)
+      : entries.find((entry) => contextId(entry) === input.contextId);
+    if (!selected || (selected.message.expectsReply && !asks.includes(selected))) throw new Error("Unknown or resolved reply selector; call intercom_pending");
+    if (input.to && selected.from.id !== input.to && selected.from.name?.toLowerCase() !== input.to.toLowerCase()) {
+      throw new Error("Reply sender does not match the selected context");
+    }
+    if (input.which) throw new Error("Do not combine an exact reply selector with which");
+    target = selected;
+  } else {
+    const to = input.to;
+    const candidates = to ? asks.filter((entry) => entry.from.id === to || entry.from.name?.toLowerCase() === to.toLowerCase() || entry.from.id.startsWith(to)) : asks;
+    if (!input.which && new Set(candidates.map((entry) => entry.message.content.team)).size > 1) {
+      throw new Error("Multiple team contexts; specify askId or contextId");
+    }
+    target = selectPendingAsk(asks, input.to, input.which);
+  }
+  if (input.team !== undefined && input.team !== target.message.content.team) {
+    throw new Error("Reply team must match the original message; omit team to inherit it");
+  }
+  return target;
+}

package/codex/runtime.ts

@@ -9,15 +9,14 @@ import { getAskTimeoutMs, loadConfig } from "../config.ts";
 import type { Attachment, Message, SessionInfo } from "../types.ts";
 import { formatIntercomTeam, resolveIntercomTeam } from "./team.ts";
 import {
-  createNamedTeam,
-  findNamedTeam,
   formatCreateSuccess,
   formatJoinableNamedTeamList,
   formatNamedJoinSuccess,
   listNamedTeams,
   parseTeamName,
-  rejectManagedJoin,
 } from "./named-teams.ts";
+import { appendNamedTeamMembership, sessionNamedTeams, namedTeamRoster, formatNamedTeamRoster, resolveNamedMessageTeam } from "./named-team-membership.ts";
+import { contextId, askId, replyHint, selectReplyContext } from "./reply-context.ts";
 
 export interface CodexRuntimeIdentity {
   sessionId: string;
@@ -77,6 +76,9 @@ function publicPendingEntry(entry: PendingInboundMessage, selector?: string): Re
       ...(entry.from.parentSessionId ? { parent_session_id: entry.from.parentSessionId } : {}),
       ...(entry.from.generation ? { generation: entry.from.generation } : {}),
     },
+    contextId: contextId(entry),
+    ...(entry.message.expectsReply ? { askId: askId(entry) } : {}),
+    ...(entry.message.content.team ? { team: entry.message.content.team } : {}),
     received_at: entry.receivedAt,
     read: entry.read,
     text: entry.message.content.text,
@@ -95,6 +97,7 @@ export interface ToolResult {
 interface ReplyWaiter {
   from: string;
   replyTo: string;
+  team?: string;
   resolve: (message: Message) => void;
   reject: (error: Error) => void;
   timeout: NodeJS.Timeout;
@@ -349,25 +352,23 @@ export class CodexIntercomRuntime {
     await this.connect();
   }
 
-  async join(name?: string, create = false): Promise<ToolResult> {
-    const blocked = rejectManagedJoin();
-    if (blocked) return textResult(blocked, { ok: false }, true);
+  async join(name?: string, create = false, members?: string[], work?: string): Promise<ToolResult> {
     try {
-      if (create) {
-        if (typeof name !== "string" || !name.trim()) {
-          return textResult("Creating a team requires a name.", { ok: false }, true);
-        }
-        const team = createNamedTeam({ name: parseTeamName(name), managerSessionId: this.identity.sessionId });
-        await this.switchRuntimeScope(team.scopeId, team.managerSessionId);
-        return textResult(formatCreateSuccess({ team: team.name, name: this.identity.name }), { ok: true, team: team.name, role: "manager" });
-      }
       if (!name?.trim()) {
+        if (create || members?.length || work !== undefined) throw new Error("Creating or extending a team requires a name");
         return textResult(formatJoinableNamedTeamList(listNamedTeams()));
       }
-      const team = findNamedTeam(parseTeamName(name));
-      if (!team) return textResult("Could not join that team.", { ok: false }, true);
-      await this.switchRuntimeScope(team.scopeId, team.managerSessionId);
-      return textResult(formatNamedJoinSuccess({ team: team.name, name: this.identity.name }), { ok: true, team: team.name, role: "teammate" });
+      const client = await this.connect();
+      const sessions = await client.listSessions();
+      const memberIds = (members ?? []).map((member) => {
+        const id = resolveSessionTarget(sessions, member);
+        if (!id) throw new Error(`Session "${member}" is not connected`);
+        return id;
+      });
+      const team = await appendNamedTeamMembership({ name: parseTeamName(name), selfId: this.identity.sessionId, members: memberIds, create, work });
+      const roster = namedTeamRoster(team, this.identity.sessionId, sessions);
+      const notice = create ? formatCreateSuccess({ team: team.name, name: this.identity.name }) : formatNamedJoinSuccess({ team: team.name, name: this.identity.name });
+      return textResult(`${notice}\nOther team memberships are unchanged.`, { ok: true, team: team.name, role: roster.self.isManager ? "manager" : "member", roster });
     } catch (error) {
       return textResult(error instanceof Error ? error.message : String(error), { ok: false }, true);
     }
@@ -378,7 +379,7 @@ export class CodexIntercomRuntime {
     if (waiter) {
       const senderTarget = from.name || from.id;
       const fromMatches = senderTarget.toLowerCase() === waiter.from.toLowerCase() || from.id === waiter.from;
-      if (fromMatches) {
+      if (fromMatches && message.content.team === waiter.team) {
         this.replyWaiters.delete(waiter.replyTo);
         clearTimeout(waiter.timeout);
         waiter.cleanup?.();
@@ -394,7 +395,7 @@ export class CodexIntercomRuntime {
     }
   }
 
-  private waitForReply(from: string, replyTo: string, timeoutMs = getAskTimeoutMs(), signal?: AbortSignal): Promise<Message> {
+  private waitForReply(from: string, replyTo: string, timeoutMs = getAskTimeoutMs(), signal?: AbortSignal, team?: string): Promise<Message> {
     return new Promise((resolve, reject) => {
       if (signal?.aborted) {
         reject(new Error("intercom_ask cancelled"));
@@ -418,7 +419,7 @@ export class CodexIntercomRuntime {
         reject(new Error(`No reply from "${from}" within ${Math.round(timeoutMs / 1000)} seconds`));
       }, timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
-      this.replyWaiters.set(replyTo, { from, replyTo, resolve, reject, timeout, cleanup });
+      this.replyWaiters.set(replyTo, { from, replyTo, team, resolve, reject, timeout, cleanup });
     });
   }
 
@@ -437,9 +438,16 @@ export class CodexIntercomRuntime {
     );
   }
 
-  async team(): Promise<ToolResult> {
+  async team(name?: string): Promise<ToolResult> {
     const client = await this.connect();
     const sessions = await client.listSessions();
+    const mine = sessionNamedTeams(this.identity.sessionId);
+    const selected = name ? mine.filter((entry) => entry.name === name) : mine;
+    if (name && !selected.length) return textResult(`You do not belong to team "${name}"`, { ok: false }, true);
+    if (selected.length) {
+      const teams = selected.map((entry) => namedTeamRoster(entry, this.identity.sessionId, sessions));
+      return textResult(teams.map(formatNamedTeamRoster).join("\n\n"), { teams });
+    }
     const team = await resolveIntercomTeam({ selfId: client.sessionId ?? this.identity.sessionId, sessions });
     return textResult(formatIntercomTeam(team), team as unknown as Record<string, unknown>);
   }
@@ -482,10 +490,14 @@ export class CodexIntercomRuntime {
     return textResult("Summary updated.", { ok: true, summary });
   }
 
-  async send(to: string, message: string, attachments?: Attachment[], replyTo?: string): Promise<ToolResult> {
+  async send(to: string, message: string, attachments?: Attachment[], replyTo?: string, requestedTeam?: string): Promise<ToolResult> {
     const client = await this.connect();
     const sendTo = await this.resolveTarget(to);
-    const result = await client.send(sendTo, { text: message, attachments, replyTo });
+    const source = replyTo ? this.unread.find((entry) => entry.message.id === replyTo && entry.from.id === sendTo) : undefined;
+    if (replyTo && !source) throw new Error("Unknown inbound reply context");
+    if (source && requestedTeam !== undefined && requestedTeam !== source.message.content.team) throw new Error("Reply team must match the original message");
+    const team = source ? source.message.content.team : resolveNamedMessageTeam(this.identity.sessionId, sendTo, requestedTeam);
+    const result = await client.send(sendTo, { text: message, attachments, replyTo: source?.message.expectsReply ? replyTo : undefined, team });
     if (!result.delivered) {
       return textResult(`Message to "${to}" was not delivered: ${result.reason ?? "Session may not exist or has disconnected."}`, { ok: false, message_id: result.id, reason: result.reason }, true);
     }
@@ -493,11 +505,12 @@ export class CodexIntercomRuntime {
     return textResult(`Message sent to ${to}.`, { ok: true, message_id: result.id, to });
   }
 
-  async ask(to: string, message: string, attachments?: Attachment[], timeoutMs = getAskTimeoutMs(), signal?: AbortSignal): Promise<ToolResult> {
+  async ask(to: string, message: string, attachments?: Attachment[], timeoutMs = getAskTimeoutMs(), signal?: AbortSignal, requestedTeam?: string): Promise<ToolResult> {
     const client = await this.connect();
     const sendTo = await this.resolveTarget(to);
+    const team = resolveNamedMessageTeam(this.identity.sessionId, sendTo, requestedTeam);
     const questionId = randomUUID();
-    const replyPromise = this.waitForReply(sendTo, questionId, timeoutMs, signal);
+    const replyPromise = this.waitForReply(sendTo, questionId, timeoutMs, signal, team);
     void replyPromise.catch(() => undefined);
     try {
       const result = await client.send(sendTo, {
@@ -505,6 +518,7 @@ export class CodexIntercomRuntime {
         text: message,
         attachments,
         expectsReply: true,
+        team,
       });
       if (!result.delivered) {
         this.replyWaiters.get(questionId)?.reject(new Error(result.reason ?? "Session may not exist or has disconnected."));
@@ -529,12 +543,12 @@ export class CodexIntercomRuntime {
     const pendingAsks = Array.from(this.unresolvedAsks.values()).sort((a, b) => a.receivedAt - b.receivedAt);
     const lines = [
       unreadMessages.length
-        ? unreadMessages.map((entry) => `- ${formatSessionDisplay(entry.from)}: ${entry.message.content.text}${formatAttachments(entry.message.content.attachments)}`).join("\n")
+        ? unreadMessages.map((entry) => `- ${formatSessionDisplay(entry.from)}${replyHint(entry)}: ${entry.message.content.text}${formatAttachments(entry.message.content.attachments)}`).join("\n")
         : "No unread messages.",
       pendingAsks.length
         ? `\nPending asks:\n${pendingAsks.map((entry) => {
           const selector = pendingSelector(pendingAsks, entry);
-          return `- ${formatSessionDisplay(entry.from)}${selector ? ` [${selector}]` : ""}: ${entry.message.content.text}`;
+          return `- ${formatSessionDisplay(entry.from)}${replyHint(entry)}${selector ? ` [${selector}]` : ""}: ${entry.message.content.text}`;
         }).join("\n")}`
         : "",
     ].filter(Boolean);
@@ -544,10 +558,10 @@ export class CodexIntercomRuntime {
     });
   }
 
-  async reply(message: string, to?: string, which?: ReplyWhich): Promise<ToolResult> {
+  async reply(message: string, to?: string, which?: ReplyWhich, askId?: string, contextId?: string, team?: string): Promise<ToolResult> {
     let target: PendingInboundMessage;
     try {
-      target = selectPendingAsk(Array.from(this.unresolvedAsks.values()), to, which);
+      target = selectReplyContext(this.unread, Array.from(this.unresolvedAsks.values()), { to, which, askId, contextId, team });
     } catch (error) {
       return textResult(error instanceof Error ? error.message : String(error), { ok: false }, true);
     }

package/codex/team-guidance.ts

@@ -0,0 +1,7 @@
+export const TASK_TEAM_GUIDANCE = `Intercom task-team rules:
+- When the user delegates to named peers and this task has no approved team, ask once whether to form a team with you and those peers. Wait for approval before creating a team or adding peers. An explicit create/join request is approval; never ask again for an approved task or inbound team message.
+- After approval, discover the connected peers, then intercom_join({ name: "launch", create: true, members: ["front", "writer"], work: "Current task" }) adds everyone in one call. Do not ask the user to join each terminal manually.
+- Membership is additive: joining another team preserves previous teams. Reuse the approved team for the same task; a different task may need a different team.
+- Initial contact without a shared team is allowed: omit team for an ungrouped direct message. Unrelated team memberships must not prevent contact or silently create teams.
+- Include team on task sends/asks, especially when peers share multiple teams. Replies inherit the original message's team via askId or contextId from intercom_pending; never override it using a current team or mix contexts from different tasks.
+- Use intercom_send for assignments, progress/status requests, notifications and follow-ups. Use intercom_ask only when your next step genuinely depends on the answer; keep only one unresolved ask per recipient.`;