pi-extended-teams 2.1.16

package/src/utils/messaging.ts

@@ -0,0 +1,441 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { writeJsonAtomic } from "./atomic-json";
+import { InboxMessage, TeamConfig } from "./models";
+import { withLock } from "./lock";
+import { configPath, inboxPath } from "./paths";
+import { readConfig } from "./teams";
+import { assertLifecycleTombstoneAbsent, withLifecycleTombstoneLock } from "./lifecycle-tombstone";
+
+export interface MessageMetadataOptions {
+  id?: string;
+  operationId?: string;
+  workflowRunId?: string;
+  metadata?: Record<string, any>;
+  /** Admission fence for startup messages that belong to one lifecycle run. */
+  expectedRecipientRunId?: string;
+}
+
+export interface SendPlainMessageOptions extends MessageMetadataOptions {
+  color?: string;
+}
+
+export interface SendPlainMessageOnceResult {
+  message: InboxMessage;
+  delivered: boolean;
+}
+
+export interface ReadInboxTailOptions {
+  unreadOnly?: boolean;
+  markAsRead?: boolean;
+}
+
+export function nowIso(): string {
+  return new Date().toISOString();
+}
+
+interface AppendRunningMessageOptions {
+  operationId?: string;
+  workflowRunId?: string;
+  expectedRecipientRunId?: string;
+}
+
+async function appendRunningMessage(
+  teamName: string,
+  agentName: string,
+  message: InboxMessage,
+  options: AppendRunningMessageOptions = {}
+): Promise<SendPlainMessageOnceResult> {
+  const appendUnderInboxLock = async (): Promise<SendPlainMessageOnceResult> => {
+    const p = ensureInboxFile(teamName, agentName);
+    return withLock(p, async () => {
+      const messages = readInboxRaw(p);
+      if (options.operationId) {
+        const existing = messages.find(item => messageOperationMatches(item, options.operationId!, options.workflowRunId));
+        if (existing) return { message: existing, delivered: false };
+      }
+      messages.push(message);
+      writeJsonAtomic(p, messages);
+      return { message, delivered: true };
+    });
+  };
+
+  // The lead has always been an out-of-band recipient: final reports must remain
+  // deliverable after the sender is fenced and the lead roster entry has no run id.
+  if (agentName === "team-lead") return appendUnderInboxLock();
+
+  const teamConfigPath = configPath(teamName);
+  return withLifecycleTombstoneLock(teamName, agentName, async lifecycleLock => {
+    assertLifecycleTombstoneAbsent(teamName, agentName, lifecycleLock.read());
+    return withLock(teamConfigPath, async () => {
+      if (!fs.existsSync(teamConfigPath)) {
+        throw new Error(`Cannot send message to ${agentName}: agent is not running.`);
+      }
+      const config = JSON.parse(fs.readFileSync(teamConfigPath, "utf-8")) as TeamConfig;
+      const recipient = Array.isArray(config.members)
+        ? config.members.find(member => member.name === agentName)
+        : undefined;
+      if (
+        !recipient
+        || recipient.isActive === false
+        || (options.expectedRecipientRunId !== undefined && recipient.lifecycleRunId !== options.expectedRecipientRunId)
+      ) {
+        throw new Error(`Cannot send message to ${agentName}: agent is not running.`);
+      }
+      return appendUnderInboxLock();
+    });
+  });
+}
+
+export async function requireRunningMessageRecipient(teamName: string, recipient: string): Promise<void> {
+  if (recipient === "team-lead") return;
+  const teamConfigPath = configPath(teamName);
+  await withLifecycleTombstoneLock(teamName, recipient, async lifecycleLock => {
+    assertLifecycleTombstoneAbsent(teamName, recipient, lifecycleLock.read());
+    await withLock(teamConfigPath, async () => {
+      if (!fs.existsSync(teamConfigPath)) throw new Error(`Cannot send message to ${recipient}: agent is not running.`);
+      const config = JSON.parse(fs.readFileSync(teamConfigPath, "utf-8")) as TeamConfig;
+      const recipientMember = config.members.find(member => member.name === recipient);
+      if (!recipientMember || recipientMember.isActive === false) {
+        throw new Error(`Cannot send message to ${recipient}: agent is not running.`);
+      }
+    });
+  });
+}
+
+export async function sendPlainMessageIfRunning(
+  teamName: string,
+  fromName: string,
+  toName: string,
+  text: string,
+  summary: string,
+  color?: string,
+  options: MessageMetadataOptions = {}
+): Promise<void> {
+  const message = buildInboxMessage(fromName, text, summary, { ...options, color });
+  await appendRunningMessage(teamName, toName, message, {
+    expectedRecipientRunId: options.expectedRecipientRunId,
+  });
+}
+
+function ensureInboxFile(teamName: string, agentName: string): string {
+  const p = inboxPath(teamName, agentName);
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return p;
+}
+
+function readInboxRaw(p: string): InboxMessage[] {
+  if (!fs.existsSync(p)) return [];
+  const parsed = JSON.parse(fs.readFileSync(p, "utf-8"));
+  return Array.isArray(parsed) ? parsed : [];
+}
+
+export function messageOperationMatches(message: InboxMessage, operationId: string, workflowRunId?: string): boolean {
+  const messageOperationId = message.operationId || message.metadata?.operationId;
+  const messageWorkflowRunId = message.workflowRunId || message.metadata?.workflowRunId;
+  return messageOperationId === operationId && (workflowRunId === undefined || messageWorkflowRunId === workflowRunId);
+}
+
+function cloneInboxMessage(message: InboxMessage): InboxMessage {
+  return {
+    ...message,
+    metadata: message.metadata ? { ...message.metadata } : undefined,
+  };
+}
+
+function cloneInboxMessages(messages: InboxMessage[]): InboxMessage[] {
+  return messages.map(cloneInboxMessage);
+}
+
+function normalizeInboxLimit(limit: number): number {
+  if (!Number.isInteger(limit) || limit < 0) {
+    throw new Error("Inbox limit must be a non-negative integer");
+  }
+  return limit;
+}
+
+function selectInboxMessages(allMsgs: InboxMessage[], unreadOnly: boolean, limit?: number): InboxMessage[] {
+  const matches = (message: InboxMessage) => !unreadOnly || !message.read;
+
+  if (limit === undefined) {
+    return unreadOnly ? allMsgs.filter(matches) : allMsgs;
+  }
+
+  const normalizedLimit = normalizeInboxLimit(limit);
+  if (normalizedLimit === 0) return [];
+
+  const result: InboxMessage[] = [];
+  for (let index = allMsgs.length - 1; index >= 0 && result.length < normalizedLimit; index--) {
+    const message = allMsgs[index];
+    if (matches(message)) result.push(message);
+  }
+
+  return result.reverse();
+}
+
+function markMessagesRead(messages: InboxMessage[]): boolean {
+  let changed = false;
+  for (const message of messages) {
+    if (!message.read) {
+      message.read = true;
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+export async function appendMessage(teamName: string, agentName: string, message: InboxMessage) {
+  const p = ensureInboxFile(teamName, agentName);
+
+  await withLock(p, async () => {
+    const msgs = readInboxRaw(p);
+    msgs.push(message);
+    writeJsonAtomic(p, msgs);
+  });
+}
+
+export async function appendMessageOnce(
+  teamName: string,
+  agentName: string,
+  message: InboxMessage & { operationId: string }
+): Promise<SendPlainMessageOnceResult> {
+  const p = ensureInboxFile(teamName, agentName);
+
+  return await withLock(p, async () => {
+    const msgs = readInboxRaw(p);
+    const existing = msgs.find((item) => messageOperationMatches(item, message.operationId, message.workflowRunId));
+    if (existing) return { message: existing, delivered: false };
+
+    msgs.push(message);
+    writeJsonAtomic(p, msgs);
+    return { message, delivered: true };
+  });
+}
+
+export async function appendMessageOnceIfRunning(
+  teamName: string,
+  agentName: string,
+  message: InboxMessage & { operationId: string },
+  options: Pick<MessageMetadataOptions, "expectedRecipientRunId"> = {}
+): Promise<SendPlainMessageOnceResult> {
+  return appendRunningMessage(teamName, agentName, message, {
+    operationId: message.operationId,
+    workflowRunId: message.workflowRunId,
+    expectedRecipientRunId: options.expectedRecipientRunId,
+  });
+}
+
+export async function readInbox(
+  teamName: string,
+  agentName: string,
+  unreadOnly = false,
+  markAsRead = true
+): Promise<InboxMessage[]> {
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) return [];
+
+  return await withLock(p, async () => {
+    const allMsgs = readInboxRaw(p);
+    const result = selectInboxMessages(allMsgs, unreadOnly);
+
+    if (markAsRead && result.length > 0 && markMessagesRead(result)) {
+      writeJsonAtomic(p, allMsgs);
+    }
+
+    return cloneInboxMessages(result);
+  });
+}
+
+export async function readInboxTail(
+  teamName: string,
+  agentName: string,
+  limit: number,
+  options: ReadInboxTailOptions = {}
+): Promise<InboxMessage[]> {
+  const normalizedLimit = normalizeInboxLimit(limit);
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) return [];
+
+  return await withLock(p, async () => {
+    const allMsgs = readInboxRaw(p);
+    const result = selectInboxMessages(allMsgs, options.unreadOnly === true, normalizedLimit);
+
+    if (options.markAsRead === true && result.length > 0 && markMessagesRead(result)) {
+      writeJsonAtomic(p, allMsgs);
+    }
+
+    return cloneInboxMessages(result);
+  });
+}
+
+export async function removeInboxMessagesByOperationUnderLifecycleLock(
+  teamName: string,
+  agentName: string,
+  operationId: string,
+  workflowRunId?: string
+): Promise<number> {
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) return 0;
+
+  return withLock(p, async () => {
+    if (!fs.existsSync(p)) return 0;
+    const messages = readInboxRaw(p);
+    const remaining = messages.filter((message) => !messageOperationMatches(message, operationId, workflowRunId));
+    const removed = messages.length - remaining.length;
+    if (removed > 0) writeJsonAtomic(p, remaining);
+    return removed;
+  });
+}
+
+export async function findInboxMessageByOperation(
+  teamName: string,
+  agentName: string,
+  operationId: string,
+  workflowRunId?: string
+): Promise<InboxMessage | undefined> {
+  const p = inboxPath(teamName, agentName);
+  if (!fs.existsSync(p)) return undefined;
+
+  return await withLock(p, async () => {
+    const message = readInboxRaw(p).find((item) => messageOperationMatches(item, operationId, workflowRunId));
+    return message ? cloneInboxMessage(message) : undefined;
+  });
+}
+
+export function buildInboxMessage(
+  fromName: string,
+  text: string,
+  summary: string,
+  options: SendPlainMessageOptions = {}
+): InboxMessage {
+  return {
+    id: options.id || crypto.randomUUID(),
+    from: fromName,
+    text,
+    timestamp: nowIso(),
+    read: false,
+    summary,
+    color: options.color,
+    operationId: options.operationId,
+    workflowRunId: options.workflowRunId,
+    metadata: options.metadata,
+  };
+}
+
+export async function sendPlainMessage(
+  teamName: string,
+  fromName: string,
+  toName: string,
+  text: string,
+  summary: string,
+  color?: string,
+  options: MessageMetadataOptions = {}
+) {
+  const msg = buildInboxMessage(fromName, text, summary, { ...options, color });
+  await appendMessage(teamName, toName, msg);
+}
+
+export async function sendPlainMessageOnce(
+  teamName: string,
+  fromName: string,
+  toName: string,
+  text: string,
+  summary: string,
+  options: SendPlainMessageOptions & { operationId: string }
+): Promise<SendPlainMessageOnceResult> {
+  const msg = buildInboxMessage(fromName, text, summary, options) as InboxMessage & { operationId: string };
+  return await appendMessageOnce(teamName, toName, msg);
+}
+
+export async function sendPlainMessageOnceIfRunning(
+  teamName: string,
+  fromName: string,
+  toName: string,
+  text: string,
+  summary: string,
+  options: SendPlainMessageOptions & { operationId: string }
+): Promise<SendPlainMessageOnceResult> {
+  const msg = buildInboxMessage(fromName, text, summary, options) as InboxMessage & { operationId: string };
+  return appendMessageOnceIfRunning(teamName, toName, msg, {
+    expectedRecipientRunId: options.expectedRecipientRunId,
+  });
+}
+
+export async function peekInbox(
+  teamName: string,
+  agentName: string,
+  unreadOnly = false
+): Promise<InboxMessage[]> {
+  return await readInbox(teamName, agentName, unreadOnly, false);
+}
+
+/**
+ * Broadcasts a message to all team members except the sender.
+ * @param teamName The name of the team
+ * @param fromName The name of the sender
+ * @param text The message text
+ * @param summary A short summary of the message
+ * @param color An optional color for the message
+ */
+export async function broadcastMessage(
+  teamName: string,
+  fromName: string,
+  text: string,
+  summary: string,
+  color?: string,
+  options: MessageMetadataOptions = {}
+) {
+  const config = await readConfig(teamName);
+
+  // Create an array of delivery promises for all members except the sender
+  const deliveryPromises = config.members
+    .filter((member) => member.name !== fromName)
+    .map((member) => sendPlainMessageIfRunning(teamName, fromName, member.name, text, summary, color, options));
+
+  // Execute deliveries in parallel and wait for all to settle
+  const results = await Promise.allSettled(deliveryPromises);
+
+  // Log failures for diagnostics
+  const failures = results.filter((r): r is PromiseRejectedResult => r.status === "rejected");
+  if (failures.length > 0) {
+    console.error(`Broadcast partially failed: ${failures.length} messages could not be delivered.`);
+    // Optionally log individual errors
+    failures.forEach((f) => console.error(`- Delivery error:`, f.reason));
+  }
+}
+
+export interface BroadcastMessageOnceRecipientResult {
+  recipient: string;
+  delivered: boolean;
+  message?: InboxMessage;
+  error?: string;
+}
+
+export async function broadcastMessageOnce(
+  teamName: string,
+  fromName: string,
+  text: string,
+  summary: string,
+  options: SendPlainMessageOptions & { operationId: string }
+): Promise<BroadcastMessageOnceRecipientResult[]> {
+  const config = await readConfig(teamName);
+  const recipients = config.members
+    .filter((member) => member.name !== fromName)
+    .map((member) => member.name);
+  // Report every recipient; operation IDs make retries idempotent.
+  const results = await Promise.allSettled(
+    recipients.map((recipient) => sendPlainMessageOnceIfRunning(teamName, fromName, recipient, text, summary, options))
+  );
+
+  return results.map((result, index) => (
+    result.status === "fulfilled"
+      ? { recipient: recipients[index], ...result.value }
+      : {
+          recipient: recipients[index],
+          delivered: false,
+          error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+        }
+  ));
+}

package/src/utils/model-resolution.test.ts

@@ -0,0 +1,231 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  buildPreferredModelsFromSettings,
+  isKnownQualifiedModel,
+  isQualifiedModel,
+  listPreferredQualifiedModels,
+  loadModelResolutionConfig,
+  loadPiModelSettings,
+  normalizeQualifiedModel,
+  parseQualifiedModel,
+  sortAvailableModels,
+  stripThinkingSuffix,
+  type AvailableModel,
+} from "./model-resolution";
+
+const availableModels: AvailableModel[] = [
+  { provider: "openrouter", model: "gpt-5" },
+  { provider: "openai-codex", model: "gpt-5.4" },
+  { provider: "claude-agent-sdk", model: "claude-sonnet-4-6" },
+  { provider: "claude-agent-sdk", model: "claude-opus-4-7" },
+  { provider: "kimi-coding", model: "kimi-for-coding" },
+];
+
+describe("qualified model helpers", () => {
+  it("parses qualified models", () => {
+    expect(parseQualifiedModel("openai-codex/gpt-5.4")).toEqual({
+      provider: "openai-codex",
+      model: "gpt-5.4",
+    });
+  });
+
+  it("strips thinking suffixes", () => {
+    expect(stripThinkingSuffix("openai-codex/gpt-5.4:high")).toBe("openai-codex/gpt-5.4");
+    expect(stripThinkingSuffix("openai-codex/gpt-5.4:max")).toBe("openai-codex/gpt-5.4");
+  });
+
+  it("detects qualified models", () => {
+    expect(isQualifiedModel("openai-codex/gpt-5.4")).toBe(true);
+    expect(isQualifiedModel("gpt-5")).toBe(false);
+  });
+
+  it("normalizes qualified models", () => {
+    expect(normalizeQualifiedModel("openai-codex/gpt-5.4:high")).toBe("openai-codex/gpt-5.4");
+    expect(normalizeQualifiedModel("gpt-5")).toBeNull();
+  });
+
+  it("checks known qualified models", () => {
+    expect(isKnownQualifiedModel("openai-codex/gpt-5.4", availableModels)).toBe(true);
+    expect(isKnownQualifiedModel("openrouter/gpt-4o", availableModels)).toBe(false);
+  });
+});
+
+describe("loadModelResolutionConfig", () => {
+  const testRoot = path.join(os.tmpdir(), `pi-extended-teams-model-config-${Date.now()}`);
+  const homeDir = path.join(testRoot, "home");
+  const projectDir = path.join(testRoot, "project");
+
+  beforeEach(() => {
+    fs.rmSync(testRoot, { recursive: true, force: true });
+    fs.mkdirSync(path.join(homeDir, ".pi"), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, ".pi"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(testRoot, { recursive: true, force: true });
+  });
+
+  it("loads empty defaults when no config files exist", () => {
+    fs.rmSync(path.join(homeDir, ".pi"), { recursive: true, force: true });
+    fs.rmSync(path.join(projectDir, ".pi"), { recursive: true, force: true });
+
+    const config = loadModelResolutionConfig({ homeDir, projectDir });
+
+    expect(config.providerPriority).toEqual([]);
+  });
+
+  it("loads global config", () => {
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "pi-extended-teams.json"),
+      JSON.stringify({ providerPriority: ["openai-codex", "claude-agent-sdk"] }, null, 2)
+    );
+
+    const config = loadModelResolutionConfig({ homeDir, projectDir });
+
+    expect(config.providerPriority).toEqual(["openai-codex", "claude-agent-sdk"]);
+  });
+
+  it("lets project config override global config", () => {
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "pi-extended-teams.json"),
+      JSON.stringify({ providerPriority: ["claude-agent-sdk"] }, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(projectDir, ".pi", "pi-extended-teams.json"),
+      JSON.stringify({ providerPriority: ["openai-codex"] }, null, 2)
+    );
+
+    const config = loadModelResolutionConfig({ homeDir, projectDir });
+
+    expect(config.providerPriority).toEqual(["openai-codex"]);
+  });
+
+  it("keeps legacy pi-teams config as a lower-priority compatibility path", () => {
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "pi-teams.json"),
+      JSON.stringify({ providerPriority: ["claude-agent-sdk"] }, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "pi-extended-teams.json"),
+      JSON.stringify({ providerPriority: ["openai-codex"] }, null, 2)
+    );
+
+    const config = loadModelResolutionConfig({ homeDir, projectDir });
+
+    expect(config.providerPriority).toEqual(["openai-codex"]);
+  });
+});
+
+describe("loadPiModelSettings", () => {
+  const testRoot = path.join(os.tmpdir(), `pi-extended-teams-pi-settings-${Date.now()}`);
+  const homeDir = path.join(testRoot, "home");
+  const projectDir = path.join(testRoot, "project");
+
+  beforeEach(() => {
+    fs.rmSync(testRoot, { recursive: true, force: true });
+    fs.mkdirSync(path.join(homeDir, ".pi", "agent"), { recursive: true });
+    fs.mkdirSync(path.join(projectDir, ".pi"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(testRoot, { recursive: true, force: true });
+  });
+
+  it("loads global pi settings", () => {
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "agent", "settings.json"),
+      JSON.stringify({
+        defaultProvider: "openai-codex",
+        defaultModel: "gpt-5.4",
+        enabledModels: ["claude-*"],
+      }, null, 2)
+    );
+
+    const settings = loadPiModelSettings({ homeDir, projectDir });
+
+    expect(settings.defaultProvider).toBe("openai-codex");
+    expect(settings.defaultModel).toBe("gpt-5.4");
+    expect(settings.enabledModels).toEqual(["claude-*"]);
+  });
+
+  it("lets project pi settings override global settings", () => {
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "agent", "settings.json"),
+      JSON.stringify({ defaultProvider: "claude-agent-sdk", defaultModel: "claude-opus-4-7" }, null, 2)
+    );
+    fs.writeFileSync(
+      path.join(projectDir, ".pi", "settings.json"),
+      JSON.stringify({ defaultProvider: "openai-codex", defaultModel: "gpt-5.4" }, null, 2)
+    );
+
+    const settings = loadPiModelSettings({ homeDir, projectDir });
+
+    expect(settings.defaultProvider).toBe("openai-codex");
+    expect(settings.defaultModel).toBe("gpt-5.4");
+  });
+});
+
+describe("preferred model selection", () => {
+  it("builds preferred models from explicit preferences and pi settings", () => {
+    const preferred = buildPreferredModelsFromSettings(
+      availableModels,
+      {
+        defaultProvider: "openai-codex",
+        defaultModel: "gpt-5.4",
+        enabledModels: ["claude-*", "kimi-for-coding"],
+      },
+      ["claude-agent-sdk/claude-opus-4-7"]
+    );
+
+    expect(preferred).toEqual([
+      "claude-agent-sdk/claude-opus-4-7",
+      "openai-codex/gpt-5.4",
+      "claude-agent-sdk/claude-sonnet-4-6",
+      "kimi-coding/kimi-for-coding",
+    ]);
+  });
+
+  it("lists preferred qualified models from on-disk settings", () => {
+    const testRoot = path.join(os.tmpdir(), `pi-extended-teams-preferred-${Date.now()}`);
+    const homeDir = path.join(testRoot, "home");
+
+    fs.mkdirSync(path.join(homeDir, ".pi", "agent"), { recursive: true });
+    fs.writeFileSync(
+      path.join(homeDir, ".pi", "agent", "settings.json"),
+      JSON.stringify({
+        defaultProvider: "openai-codex",
+        defaultModel: "gpt-5.4",
+        enabledModels: ["claude-*"],
+      }, null, 2)
+    );
+
+    const preferred = listPreferredQualifiedModels(availableModels, { homeDir });
+    expect(preferred).toEqual([
+      "openai-codex/gpt-5.4",
+      "claude-agent-sdk/claude-sonnet-4-6",
+      "claude-agent-sdk/claude-opus-4-7",
+    ]);
+
+    fs.rmSync(testRoot, { recursive: true, force: true });
+  });
+});
+
+describe("sortAvailableModels", () => {
+  it("sorts preferred models first, then provider priority, then alphabetically", () => {
+    const sorted = sortAvailableModels(availableModels, {
+      preferredModels: ["openai-codex/gpt-5.4", "claude-agent-sdk/claude-sonnet-4-6"],
+      providerPriority: ["kimi-coding", "claude-agent-sdk"],
+    });
+
+    expect(sorted.map((model) => model.qualified)).toEqual([
+      "openai-codex/gpt-5.4",
+      "claude-agent-sdk/claude-sonnet-4-6",
+      "kimi-coding/kimi-for-coding",
+      "claude-agent-sdk/claude-opus-4-7",
+      "openrouter/gpt-5",
+    ]);
+  });
+});