pi-extended-teams 2.1.16

package/extensions/tools/agent-communication-tools.test.ts

@@ -0,0 +1,306 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createAgentCommunicationTools } from "./agent-communication-tools.js";
+import * as paths from "../../src/utils/paths.js";
+import { readInbox, sendPlainMessage } from "../../src/utils/messaging.js";
+import { readRuntimeStatus } from "../../src/utils/runtime.js";
+
+let root: string;
+
+type Tool = {
+  name: string;
+  execute: (toolCallId: string, params: any) => Promise<any>;
+};
+
+function installPathSpies() {
+  vi.spyOn(paths, "teamDir").mockImplementation((teamName: unknown) => path.join(root, "teams", paths.sanitizeName(String(teamName))));
+  vi.spyOn(paths, "configPath").mockImplementation((teamName: unknown) => path.join(root, "teams", paths.sanitizeName(String(teamName)), "config.json"));
+  vi.spyOn(paths, "inboxPath").mockImplementation((teamName: unknown, agentName: unknown) => {
+    return path.join(root, "teams", paths.sanitizeName(String(teamName)), "inboxes", `${paths.sanitizeName(String(agentName))}.json`);
+  });
+  vi.spyOn(paths, "runtimeStatusPath").mockImplementation((teamName: unknown, agentName: unknown) => {
+    return path.join(root, "teams", paths.sanitizeName(String(teamName)), "runtime", `${paths.sanitizeName(String(agentName))}.json`);
+  });
+}
+
+function makeTools(teamName: string | null = "session", agentName = "reader", role: "read" | "write" = "read", lifecycleRunId: string | null = "reader-run") {
+  return new Map<string, Tool>(createAgentCommunicationTools({
+    isTeammate: true,
+    agentName,
+    role,
+    getTeamName: () => teamName ?? undefined,
+    getLifecycleRunId: () => lifecycleRunId ?? undefined,
+    authorizeWriteMember: vi.fn(async () => {}),
+    onReportAndExit: vi.fn(async () => ({ accepted: true })),
+  } as any).map((tool: Tool) => [tool.name, tool]));
+}
+
+describe("read-agent communication tools", () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-extended-teams-agent-tools-"));
+    installPathSpies();
+    const configFile = paths.configPath("session");
+    fs.mkdirSync(path.dirname(configFile), { recursive: true });
+    fs.writeFileSync(configFile, JSON.stringify({
+      name: "session",
+      members: [
+        { name: "team-lead" },
+        { name: "reader", lifecycleRunId: "reader-run", isActive: true },
+        { name: "writer", lifecycleRunId: "reader-run", isActive: true },
+      ],
+    }));
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (root && fs.existsSync(root)) fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it("still delivers inbox messages when no lifecycle run id is available", async () => {
+    await sendPlainMessage("session", "team-lead", "reader", "Initial instructions", "assignment");
+    const tools = makeTools("session", "reader", "read", null);
+
+    const result = await tools.get("read_inbox")!.execute("read", { unread_only: true });
+
+    expect(result.content[0].text).toContain("Initial instructions");
+  });
+
+  it("exposes direct communication and complete final reporting to read agents", () => {
+    const tools = Array.from(makeTools("session", "reader", "read").keys()).sort();
+
+    expect(tools).toEqual(["read_inbox", "report_and_exit", "report_progress", "send_message"]);
+  });
+
+  it("lets a read agent submit its complete result instead of replacing it with a summary", async () => {
+    const onReportAndExit = vi.fn(async () => ({
+      accepted: true,
+      cancelledDeliveries: 2,
+      deliveryOutcome: "cancelled" as const,
+    }));
+    const tools = new Map<string, Tool>(createAgentCommunicationTools({
+      isTeammate: true, agentName: "reader", role: "read", getTeamName: () => "session",
+      getLifecycleRunId: () => "reader-run",
+      authorizeWriteMember: vi.fn(async () => {}), onReportAndExit,
+    }).map((tool: Tool) => [tool.name, tool]));
+    const content = JSON.stringify({ kind: "plan", document: { title: { kind: "title", body: "Plan", children: [] }, elements: [] } });
+
+    await expect(tools.get("report_and_exit")!.execute("report", { content, summary: "Complete plan result ready" })).resolves.toMatchObject({
+      details: { accepted: true, cancelledDeliveries: 2, deliveryOutcome: "cancelled" },
+    });
+    expect(onReportAndExit).toHaveBeenCalledWith({ content, summary: "Complete plan result ready" });
+  });
+
+  it("rejects blank final reports before closing report admission", async () => {
+    const onReportAndExit = vi.fn(async () => ({ accepted: true }));
+    const tools = new Map<string, Tool>(createAgentCommunicationTools({
+      isTeammate: true, agentName: "reader", role: "read", getTeamName: () => "session",
+      getLifecycleRunId: () => "reader-run",
+      authorizeWriteMember: vi.fn(async () => {}), onReportAndExit,
+    }).map((tool: Tool) => [tool.name, tool]));
+
+    await expect(tools.get("report_and_exit")!.execute("blank-report", {
+      content: " \n\t ",
+      summary: "Not usable",
+    })).rejects.toThrow("Final report content must not be empty");
+    expect(onReportAndExit).not.toHaveBeenCalled();
+  });
+
+  it("exposes the complete coordination surface to write agents", () => {
+    const tools = Array.from(makeTools("session", "writer", "write").keys()).sort();
+
+    expect(tools).toEqual([
+      "claim_file",
+      "list_file_claims",
+      "read_inbox",
+      "release_file",
+      "report_and_exit",
+      "report_progress",
+      "send_message",
+    ]);
+  });
+
+  it("send_message uses the current session and defaults spawned agents to the lead", async () => {
+    const tools = makeTools("session", "reader");
+
+    const result = await tools.get("send_message")!.execute("send", {
+      content: "I found something useful.",
+      summary: "finding",
+    });
+
+    expect(result.details).toEqual({ session: "session", recipient: "team-lead" });
+    const inbox = await readInbox("session", "team-lead", false, false);
+    expect(inbox).toHaveLength(1);
+    expect(inbox[0]).toMatchObject({
+      from: "reader",
+      text: "I found something useful.",
+      summary: "finding",
+      read: false,
+    });
+  });
+
+  it("send_message fails when the recipient subagent is not running", async () => {
+    const configPath = paths.configPath("session");
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, JSON.stringify({ name: "session", members: [{ name: "team-lead" }, { name: "reader" }] }));
+    const tools = makeTools("session", "reader");
+
+    await expect(tools.get("send_message")!.execute("send", {
+      recipient: "finished-agent",
+      content: "Please continue.",
+    })).rejects.toThrow("Cannot send message to finished-agent: agent is not running.");
+
+    expect(await readInbox("session", "finished-agent", false, false)).toEqual([]);
+  });
+
+  it("report_progress normalizes and persists progress without inbox side effects", async () => {
+    const onProgress = vi.fn();
+    const tools = new Map<string, Tool>(createAgentCommunicationTools({
+      isTeammate: true,
+      agentName: "reader",
+      role: "read",
+      getTeamName: () => "session",
+      getLifecycleRunId: () => "reader-run",
+      authorizeWriteMember: vi.fn(async () => {}),
+      onProgress,
+      onReportAndExit: vi.fn(async () => ({ accepted: true })),
+    }).map((tool: Tool) => [tool.name, tool]));
+
+    const result = await tools.get("report_progress")!.execute("progress", {
+      status: "  Reviewing\n runtime   state  ",
+    });
+
+    expect(result.content[0].text).toBe("Progress updated: Reviewing runtime state");
+    expect(result.details).toMatchObject({ session: "session", status: "Reviewing runtime state", updated: true });
+    expect(onProgress).toHaveBeenCalledWith("Reviewing runtime state", expect.any(Number));
+    expect(await readRuntimeStatus("session", "reader")).toMatchObject({
+      latestProgress: "Reviewing runtime state",
+      progressUpdatedAt: expect.any(Number),
+    });
+    expect(await readInbox("session", "team-lead", false, false)).toEqual([]);
+    expect(await readInbox("session", "reader", false, false)).toEqual([]);
+  });
+
+  it("strips terminal control sequences from persisted progress", async () => {
+    const onProgress = vi.fn();
+    const tools = new Map<string, Tool>(createAgentCommunicationTools({
+      isTeammate: true,
+      agentName: "reader",
+      role: "read",
+      getTeamName: () => "session",
+      getLifecycleRunId: () => "reader-run",
+      authorizeWriteMember: vi.fn(async () => {}),
+      onProgress,
+      onReportAndExit: vi.fn(async () => ({ accepted: true })),
+    }).map((tool: Tool) => [tool.name, tool]));
+
+    await tools.get("report_progress")!.execute("progress", {
+      status: "Inspecting\u001b[2J files\u001b]52;c;payload\u0007 now\u001b[31m",
+    });
+
+    expect(onProgress).toHaveBeenCalledWith("Inspecting files now", expect.any(Number));
+    expect(await readRuntimeStatus("session", "reader")).toMatchObject({ latestProgress: "Inspecting files now" });
+  });
+
+  it("report_progress rejects empty and overlong normalized statuses", async () => {
+    const tool = makeTools("session", "reader").get("report_progress")!;
+
+    await expect(tool.execute("empty", { status: " \n\t " })).rejects.toThrow("status must not be empty");
+    await expect(tool.execute("long", { status: "x".repeat(121) })).rejects.toThrow("status must be at most 120 characters");
+    expect(await readRuntimeStatus("session", "reader")).toBeNull();
+
+    await expect(tool.execute("boundary", { status: "x".repeat(120) })).resolves.toMatchObject({
+      details: { status: "x".repeat(120) },
+    });
+  });
+
+  it("report_progress skips lifecycle-closed persistence without failing the agent turn", async () => {
+    const configFile = paths.configPath("session");
+    const config = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+    config.members = config.members.map((member: any) => member.name === "reader" ? { ...member, isActive: false } : member);
+    fs.writeFileSync(configFile, JSON.stringify(config));
+    const onProgress = vi.fn();
+    const tools = new Map<string, Tool>(createAgentCommunicationTools({
+      isTeammate: true,
+      agentName: "reader",
+      role: "read",
+      getTeamName: () => "session",
+      getLifecycleRunId: () => "reader-run",
+      authorizeWriteMember: vi.fn(async () => {}),
+      onProgress,
+      onReportAndExit: vi.fn(async () => ({ accepted: true })),
+    }).map((tool: Tool) => [tool.name, tool]));
+
+    const result = await tools.get("report_progress")!.execute("closing-progress", {
+      status: "Preparing final report",
+    });
+
+    expect(result.content[0].text).toBe("Progress update skipped: Preparing final report");
+    expect(result.details).toMatchObject({
+      session: "session",
+      status: "Preparing final report",
+      updated: false,
+      reason: "lifecycle-closed",
+    });
+    expect(onProgress).toHaveBeenCalledWith("Preparing final report", expect.any(Number));
+    expect(await readRuntimeStatus("session", "reader")).toBeNull();
+  });
+
+  it("read_inbox reads the current agent inbox and records readiness", async () => {
+    await sendPlainMessage("session", "team-lead", "reader", "Initial instructions", "assignment");
+    const tools = makeTools("session", "reader");
+
+    const result = await tools.get("read_inbox")!.execute("read", { unread_only: true });
+
+    expect(result.content[0].text).toContain("Initial instructions");
+    expect(result.details).toMatchObject({
+      session: "session",
+      targetAgent: "reader",
+      messages: [expect.objectContaining({ from: "team-lead", text: "Initial instructions" })],
+    });
+
+    const inbox = await readInbox("session", "reader", false, false);
+    expect(inbox[0].read).toBe(true);
+
+    const status = await readRuntimeStatus("session", "reader");
+    expect(status).toMatchObject({ teamName: "session", agentName: "reader", ready: true });
+    expect(typeof status?.lastHeartbeatAt).toBe("number");
+    expect(typeof status?.lastInboxReadAt).toBe("number");
+  });
+
+  it("read_inbox defaults to returning only unread messages", async () => {
+    await sendPlainMessage("session", "team-lead", "reader", "Already handled", "old");
+    await readInbox("session", "reader", true, true);
+    await sendPlainMessage("session", "team-lead", "reader", "New instruction", "new");
+    const tools = makeTools("session", "reader");
+
+    const result = await tools.get("read_inbox")!.execute("read", {});
+
+    expect(result.details.messages).toHaveLength(1);
+    expect(result.details.messages[0]).toMatchObject({ text: "New instruction", read: true });
+    expect(result.content[0].text).not.toContain("Already handled");
+  });
+
+  it("read_inbox can peek without marking read or updating readiness", async () => {
+    await sendPlainMessage("session", "team-lead", "reader", "Initial instructions", "assignment");
+    const tools = makeTools("session", "reader");
+
+    const result = await tools.get("read_inbox")!.execute("read", { unread_only: true, mark_as_read: false });
+
+    expect(result.content[0].text).toContain("Initial instructions");
+    expect(result.details.markAsRead).toBe(false);
+    const inbox = await readInbox("session", "reader", false, false);
+    expect(inbox[0].read).toBe(false);
+    expect(await readRuntimeStatus("session", "reader")).toBeNull();
+  });
+
+  it("requires current session context for communication tools", async () => {
+    const tools = makeTools(null, "reader");
+
+    await expect(tools.get("send_message")!.execute("send", {
+      content: "hello",
+      summary: "hello",
+    })).rejects.toThrow("No active agent session context is available.");
+  });
+});

package/extensions/tools/agent-communication-tools.ts

@@ -0,0 +1,183 @@
+import { Type } from "@sinclair/typebox";
+import * as messaging from "../../src/utils/messaging";
+import * as runtime from "../../src/utils/runtime";
+import * as claims from "../../src/utils/claims";
+import { formatInboxMessagesForModel, sanitizePlainTuiLine } from "../ui/renderers";
+import { createFileClaimTools } from "./file-claim-tools";
+
+export interface SubmittedAgentReport {
+  content: string;
+  summary?: string;
+}
+
+export interface AgentReportSubmissionResult {
+  accepted: boolean;
+  cancelledDeliveries?: number;
+  deliveryOutcome?: "cancelled" | "none";
+}
+
+export interface AgentCommunicationToolsOptions {
+  isTeammate: boolean;
+  agentName: string;
+  role: "read" | "write";
+  getTeamName(): string | null | undefined;
+  getLifecycleRunId(): string | undefined;
+  authorizeWriteMember(teamName: string, agentName: string): Promise<void>;
+  onProgress?(status: string, updatedAt: number): void;
+  onReportAndExit(report: SubmittedAgentReport): Promise<AgentReportSubmissionResult>;
+}
+
+function requireCurrentSession(options: Pick<AgentCommunicationToolsOptions, "getTeamName">): string {
+  const teamName = options.getTeamName();
+  if (!teamName) throw new Error("No active agent session context is available.");
+  return teamName;
+}
+
+function requireLifecycleRunId(options: Pick<AgentCommunicationToolsOptions, "getLifecycleRunId">): string {
+  const runId = options.getLifecycleRunId();
+  if (!runId) throw new Error("No lifecycle run identity is available for runtime telemetry.");
+  return runId;
+}
+
+function normalizeProgressStatus(value: unknown): string {
+  if (typeof value !== "string") throw new Error("status must be a string.");
+  const status = sanitizePlainTuiLine(value).replace(/\s+/g, " ").trim();
+  if (!status) throw new Error("status must not be empty.");
+  if (status.length > 120) throw new Error("status must be at most 120 characters.");
+  return status;
+}
+
+function normalizeFinalReportContent(value: unknown): string {
+  if (typeof value !== "string") throw new Error("Final report content must be a string.");
+  const content = value.trim();
+  if (!content) throw new Error("Final report content must not be empty.");
+  return content;
+}
+
+export function createReportProgressTool(options: Pick<AgentCommunicationToolsOptions, "isTeammate" | "agentName" | "getTeamName" | "getLifecycleRunId" | "onProgress">): any {
+  return {
+    name: "report_progress",
+    label: "Report Progress",
+    description: "Update this agent's latest concise progress phrase without messaging or waking the lead.",
+    parameters: Type.Object({
+      status: Type.String({ minLength: 1, maxLength: 120, description: "Free-form progress phrase; normalized to one non-empty line (maximum 120 characters)." }),
+    }),
+    async execute(_toolCallId: string, params: any) {
+      if (!options.isTeammate) throw new Error("report_progress is only available to spawned agents.");
+      const teamName = requireCurrentSession(options);
+      const status = normalizeProgressStatus(params.status);
+      const updatedAt = Date.now();
+      options.onProgress?.(status, updatedAt);
+      try {
+        await runtime.writeRuntimeStatus(teamName, options.agentName, requireLifecycleRunId(options), {
+          latestProgress: status,
+          progressUpdatedAt: updatedAt,
+        });
+      } catch (error) {
+        if (!runtime.isRuntimeStatusWriteRejectedError(error)) throw error;
+        return {
+          content: [{ type: "text", text: `Progress update skipped: ${status}` }],
+          details: { session: teamName, status, updatedAt, updated: false, reason: "lifecycle-closed" },
+        };
+      }
+      return {
+        content: [{ type: "text", text: `Progress updated: ${status}` }],
+        details: { session: teamName, status, updatedAt, updated: true },
+      };
+    },
+  };
+}
+
+export function createAgentCommunicationTools(options: AgentCommunicationToolsOptions): any[] {
+  const communicationTools = [
+    {
+      name: "send_message",
+      label: "Send Message",
+      description: "Send a direct message in the current Pi session. Spawned agents default to messaging the lead.",
+      parameters: Type.Object({
+        recipient: Type.Optional(Type.String({ description: "Recipient agent name. Defaults to team-lead for spawned agents." })),
+        content: Type.String(),
+        summary: Type.Optional(Type.String()),
+      }),
+      async execute(_toolCallId: string, params: any) {
+        const teamName = requireCurrentSession(options);
+        const recipient = params.recipient || (options.isTeammate ? "team-lead" : undefined);
+        if (!recipient) throw new Error("recipient is required when the lead sends a message.");
+        await messaging.sendPlainMessageIfRunning(teamName, options.agentName, recipient, params.content, params.summary || "Message");
+        return { content: [{ type: "text", text: `Message sent to ${recipient}.` }], details: { session: teamName, recipient } };
+      },
+    },
+    createReportProgressTool(options),
+    {
+      name: "read_inbox",
+      label: "Read Inbox",
+      description: "Read this agent's inbox in the current Pi session.",
+      parameters: Type.Object({
+        unread_only: Type.Optional(Type.Boolean({ default: true })),
+        mark_as_read: Type.Optional(Type.Boolean({ default: true, description: "Set false to peek without marking messages read." })),
+      }),
+      async execute(_toolCallId: string, params: any) {
+        const teamName = requireCurrentSession(options);
+        const markAsRead = params.mark_as_read !== false;
+        const unreadOnly = params.unread_only !== false;
+        const msgs = await messaging.readInbox(teamName, options.agentName, unreadOnly, markAsRead);
+        const lifecycleRunId = options.getLifecycleRunId();
+        // Do not fail after read flags are persisted; telemetry is best-effort.
+        if (markAsRead && lifecycleRunId) {
+          await runtime.writeRuntimeStatus(teamName, options.agentName, lifecycleRunId, {
+            lastHeartbeatAt: Date.now(),
+            lastInboxReadAt: Date.now(),
+            ready: true,
+            lastError: undefined,
+          }).catch(() => {});
+        }
+        return { content: [{ type: "text", text: formatInboxMessagesForModel(msgs) }], details: { session: teamName, targetAgent: options.agentName, messages: msgs, markAsRead } };
+      },
+    },
+  ];
+
+  const reportAndExitTool = {
+    name: "report_and_exit",
+    label: "Report and Exit",
+    description: "Submit the complete final report to the lead and finish this nested agent run.",
+    parameters: Type.Object({
+      content: Type.String({ minLength: 1, description: "Complete non-empty final report to send to the lead; do not replace required output with a summary." }),
+      summary: Type.Optional(Type.String({ description: "Short report summary." })),
+    }),
+    async execute(_toolCallId: string, params: SubmittedAgentReport) {
+      const teamName = requireCurrentSession(options);
+      const content = normalizeFinalReportContent(params.content);
+      const summary = typeof params.summary === "string" && params.summary.trim() ? params.summary.trim() : undefined;
+      const result = await options.onReportAndExit({ content, summary });
+      const text = result.accepted
+        ? "Final report accepted. Finish immediately; the outer runner will release claims and stop this nested session."
+        : "A final report was already accepted for this run. This duplicate was ignored; finish immediately.";
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          session: teamName,
+          accepted: result.accepted,
+          ...(result.cancelledDeliveries === undefined ? {} : {
+            cancelledDeliveries: result.cancelledDeliveries,
+            deliveryOutcome: result.deliveryOutcome,
+          }),
+        },
+      };
+    },
+  };
+
+  if (options.role !== "write") return [...communicationTools, reportAndExitTool];
+
+  const fileClaimTools = createFileClaimTools({
+    agentName: options.agentName,
+    getAuthorizedWriteTeam: async () => {
+      const teamName = requireCurrentSession(options);
+      await options.authorizeWriteMember(teamName, options.agentName);
+      return teamName;
+    },
+    getCurrentTeam: () => requireCurrentSession(options),
+    claims,
+  });
+
+  return [...communicationTools, ...fileClaimTools, reportAndExitTool];
+}