pi-extended-teams 2.1.16

package/src/utils/terminal-adapter.ts

@@ -0,0 +1,103 @@
+/**
+ * Terminal Adapter Interface
+ *
+ * Abstracts tmux window/pane operations to provide a unified API for spawning,
+ * managing, and terminating writer screens. pi-extended-teams is tmux-only.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Options for spawning a new terminal pane
+ */
+export interface SpawnOptions {
+  /** Name/identifier for the background tmux window/pane */
+  name: string;
+  /** Working directory for the new pane */
+  cwd: string;
+  /** Command to execute in the pane */
+  command: string;
+  /** Environment variables to set (key-value pairs) */
+  env: Record<string, string>;
+  /** Optional pane ID used to create the background window in the same tmux session */
+  anchorPaneId?: string;
+}
+
+/**
+ * Terminal Adapter Interface
+ *
+ * Implementations provide tmux-specific logic for writer screen management.
+ */
+export interface TerminalAdapter {
+  /** Unique name identifier for this terminal type */
+  readonly name: string;
+
+  /**
+   * Detect if this terminal is currently available/active.
+   *
+   * @returns true if this terminal should be used
+   */
+  detect(): boolean;
+
+  /**
+   * Spawn a new background terminal screen with the given options.
+   *
+   * @param options - Spawn configuration
+   * @returns Pane ID that can be used for subsequent operations
+   * @throws Error if spawn fails
+   */
+  spawn(options: SpawnOptions): string;
+
+  /**
+   * Return the current tmux pane ID when available.
+   */
+  getCurrentPaneId?(): string | null;
+
+  /**
+   * Return the tmux window ID for a pane when available.
+   */
+  getWindowIdForPane?(paneId: string | null | undefined): string | null;
+
+  /**
+   * Focus/select a tmux pane so the user can watch it live.
+   *
+   * @returns true when the pane was selected
+   */
+  focusPane?(paneId: string): boolean;
+
+  /**
+   * Kill/terminate a terminal pane.
+   * Should be idempotent - no error if pane doesn't exist.
+   *
+   * @param paneId - The pane ID returned from spawn()
+   */
+  kill(paneId: string): void;
+
+  /**
+   * Check if a terminal pane is still alive/active.
+   *
+   * @param paneId - The pane ID returned from spawn()
+   * @returns true if pane exists and is active
+   */
+  isAlive(paneId: string): boolean;
+
+  /**
+   * Set the title of the current terminal pane.
+   * Used for identifying panes/windows in the terminal UI.
+   *
+   * @param title - The title to set
+   */
+  setTitle(title: string): void;
+}
+
+/**
+ * Base helper for adapters to execute commands synchronously.
+ */
+export function execCommand(command: string, args: string[]): { stdout: string; stderr: string; status: number | null } {
+  const result = spawnSync(command, args, { encoding: "utf-8" });
+  return {
+    stdout: result.stdout?.toString() ?? "",
+    stderr: result.stderr?.toString() ?? "",
+    status: result.status,
+  };
+}

package/src/utils/thinking-levels.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import {
+  clampThinkingLevel,
+  getSupportedThinkingLevels,
+  THINKING_LEVEL_NAMES,
+} from "./thinking-levels";
+
+describe("Pi model thinking capabilities", () => {
+  it("includes max in the canonical thinking-level list", () => {
+    expect(THINKING_LEVEL_NAMES).toEqual([
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+      "max",
+    ]);
+  });
+
+  it("exposes only off for non-reasoning models", () => {
+    expect(getSupportedThinkingLevels({ reasoning: false })).toEqual(["off"]);
+  });
+
+  it("provides standard levels by default and keeps xhigh/max opt-in", () => {
+    expect(getSupportedThinkingLevels({ reasoning: true })).toEqual([
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+    ]);
+  });
+
+  it("uses non-null model mappings to expose xhigh and max and null to hide levels", () => {
+    expect(getSupportedThinkingLevels({
+      reasoning: true,
+      thinkingLevelMap: {
+        minimal: null,
+        xhigh: "xhigh",
+        max: "max",
+      },
+    })).toEqual(["off", "low", "medium", "high", "xhigh", "max"]);
+  });
+
+  it("matches Pi's nearest-supported fallback order", () => {
+    const standardModel = { reasoning: true };
+    const maxWithoutXhigh = {
+      reasoning: true,
+      thinkingLevelMap: { high: null, xhigh: null, max: "max" },
+    };
+
+    expect(clampThinkingLevel(standardModel, "max")).toBe("high");
+    expect(clampThinkingLevel(maxWithoutXhigh, "high")).toBe("max");
+  });
+});

package/src/utils/thinking-levels.ts

@@ -0,0 +1,47 @@
+export const THINKING_LEVEL_NAMES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export type ThinkingLevelName = (typeof THINKING_LEVEL_NAMES)[number];
+
+export interface ThinkingCapableModel {
+  reasoning?: boolean;
+  thinkingLevelMap?: Partial<Record<ThinkingLevelName, string | null>>;
+}
+
+/**
+ * Mirror Pi's model-capability rules for thinking levels.
+ *
+ * Standard levels through `high` are available by default for reasoning models.
+ * `xhigh` and `max` are opt-in and require a non-null mapping on the model.
+ * Any level explicitly mapped to `null` is unsupported.
+ */
+export function getSupportedThinkingLevels(model: ThinkingCapableModel): ThinkingLevelName[] {
+  if (!model.reasoning) return ["off"];
+
+  return THINKING_LEVEL_NAMES.filter((level) => {
+    const mapped = model.thinkingLevelMap?.[level];
+    if (mapped === null) return false;
+    if (level === "xhigh" || level === "max") return mapped !== undefined;
+    return true;
+  });
+}
+
+/** Match Pi's nearest-supported fallback: requested, then higher, then lower. */
+export function clampThinkingLevel(
+  model: ThinkingCapableModel,
+  requested: ThinkingLevelName,
+): ThinkingLevelName {
+  const supported = getSupportedThinkingLevels(model);
+  if (supported.includes(requested)) return requested;
+
+  const requestedIndex = THINKING_LEVEL_NAMES.indexOf(requested);
+  for (let index = requestedIndex + 1; index < THINKING_LEVEL_NAMES.length; index += 1) {
+    const candidate = THINKING_LEVEL_NAMES[index];
+    if (supported.includes(candidate)) return candidate;
+  }
+  for (let index = requestedIndex - 1; index >= 0; index -= 1) {
+    const candidate = THINKING_LEVEL_NAMES[index];
+    if (supported.includes(candidate)) return candidate;
+  }
+
+  return supported[0] ?? "off";
+}

package/src/utils/workflow-metadata.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { isPiPromptPlanningMember, shouldSuppressLeadReportInjection } from "./workflow-metadata";
+
+describe("lead report injection policy", () => {
+  it("suppresses pi-prompt writer reports consumed through the private event channel", () => {
+    expect(isPiPromptPlanningMember({ metadata: { piPromptPlanning: { version: 1, correlation: "private" } } } as never)).toBe(true);
+    expect(shouldSuppressLeadReportInjection({ metadata: { piPromptPlanning: { version: 1, correlation: "private" } } } as never)).toBe(true);
+    expect(shouldSuppressLeadReportInjection({ metadata: { piPromptPlanning: { version: 2 } } } as never)).toBe(false);
+    expect(shouldSuppressLeadReportInjection({ metadata: {} } as never)).toBe(false);
+  });
+});

package/src/utils/workflow-metadata.ts

@@ -0,0 +1,88 @@
+import type { Member } from "./models";
+
+export type MemberMetadataLike = Pick<Member, "metadata"> | null | undefined;
+
+function asRecord(value: unknown): Record<string, any> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, any>
+    : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function booleanTrue(value: unknown): boolean {
+  return value === true;
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const values = value.map(item => stringValue(item)).filter((item): item is string => !!item);
+  return values.length > 0 ? values : [];
+}
+
+export function workflowRunIdFromMetadata(metadata: Record<string, any> | undefined): string | undefined {
+  const orchestration = asRecord(metadata?.orchestration);
+  return stringValue(metadata?.workflowRunId) || stringValue(orchestration?.workflowRunId);
+}
+
+export function operationIdFromMetadata(metadata: Record<string, any> | undefined): string | undefined {
+  const orchestration = asRecord(metadata?.orchestration);
+  return stringValue(metadata?.operationId) || stringValue(orchestration?.operationId);
+}
+
+export function memberWorkflowRunId(member: MemberMetadataLike): string | undefined {
+  return workflowRunIdFromMetadata(member?.metadata);
+}
+
+export function memberOperationId(member: MemberMetadataLike): string | undefined {
+  return operationIdFromMetadata(member?.metadata);
+}
+
+export function isWorkflowSpawnedMember(member: MemberMetadataLike): boolean {
+  return !!memberWorkflowRunId(member);
+}
+
+export function workflowPolicyForMember(member: MemberMetadataLike): Record<string, any> {
+  const metadata = member?.metadata;
+  const orchestration = asRecord(metadata?.orchestration);
+  return asRecord(metadata?.workflowPolicy)
+    || asRecord(metadata?.workflow)
+    || asRecord(orchestration?.workflowPolicy)
+    || asRecord(orchestration?.workflow)
+    || {};
+}
+
+export function workflowAllowsReadHelper(member: MemberMetadataLike): boolean {
+  if (!isWorkflowSpawnedMember(member)) return true;
+  const policy = workflowPolicyForMember(member);
+  return booleanTrue(policy.allowReadHelper) || booleanTrue(policy.allow_read_helper);
+}
+
+export function workflowAllowedSkills(member: MemberMetadataLike): string[] | true | null {
+  if (!isWorkflowSpawnedMember(member)) return true;
+  const policy = workflowPolicyForMember(member);
+  if (booleanTrue(policy.allowSkills) || booleanTrue(policy.allow_skills)) return true;
+  return stringList(policy.allowedSkills)
+    ?? stringList(policy.allowed_skills)
+    ?? stringList(policy.declaredSkills)
+    ?? stringList(policy.declared_skills)
+    ?? stringList(policy.skills)
+    ?? null;
+}
+
+export function workflowAllowsSkill(member: MemberMetadataLike, skillName: string): boolean {
+  const allowed = workflowAllowedSkills(member);
+  if (allowed === true) return true;
+  if (!allowed) return false;
+  return allowed.includes(skillName);
+}
+
+export function isPiPromptPlanningMember(member: MemberMetadataLike): boolean {
+  return asRecord(member?.metadata?.piPromptPlanning)?.version === 1;
+}
+
+export function shouldSuppressLeadReportInjection(member: MemberMetadataLike): boolean {
+  return isWorkflowSpawnedMember(member) || isPiPromptPlanningMember(member);
+}

package/src/utils/write-queue.test.ts

@@ -0,0 +1,251 @@
+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 * as paths from "./paths";
+import {
+  cancelQueuedWriteSpawn,
+  dequeueWriteSpawn,
+  dequeueWriteSpawns,
+  enqueueWriteSpawn,
+  findQueuedWriteSpawn,
+  listWriteQueue,
+  removeQueuedWriteSpawnsByName,
+  queuedWriteSpawnToMember,
+} from "./write-queue";
+
+type EnqueueWriteSpawnRequest = Parameters<typeof enqueueWriteSpawn>[1];
+
+const testDir = path.join(os.tmpdir(), "pi-extended-teams-write-queue-" + Date.now());
+const queuePath = path.join(testDir, "write-queue.json");
+const HIGH_VOLUME_WRITER_COUNT = 350;
+const HIGH_VOLUME_STAGE_BUDGET_MS = 5_000;
+const HIGH_VOLUME_TEST_TIMEOUT_MS = 15_000;
+
+function highVolumeWriterId(index: number): string {
+  return `writer-${String(index).padStart(3, "0")}`;
+}
+
+function highVolumeWriteSpawn(index: number): EnqueueWriteSpawnRequest {
+  const id = highVolumeWriterId(index);
+  return {
+    id,
+    name: id,
+    prompt: `Implement high-volume shard ${index}`,
+    cwd: testDir,
+    category: index % 2 === 0 ? "feature" : undefined,
+    modelSlot: "writing-hard",
+    planModeRequired: index % 2 === 0,
+    color: index % 2 === 0 ? "green" : "blue",
+    operationId: `scale-op-${String(index).padStart(3, "0")}`,
+    workflowRunId: "scale-run",
+    metadata: { slot: index, fanout: HIGH_VOLUME_WRITER_COUNT },
+    requestedAt: index + 1,
+  };
+}
+
+function writeFavoriteLevels() {
+  const settingsPath = path.join(testDir, ".pi", "agent", "pi-extended-teams", "settings.json");
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify({
+    favoriteModels: {
+      "read-review": { model: "provider/model", thinking: "xhigh" },
+      "writing-basic": { model: "provider/model", thinking: "high" },
+      "writing-hard": { model: "provider/model", thinking: "xhigh" },
+    },
+  }));
+}
+
+describe("write queue utilities", () => {
+  beforeEach(() => {
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+    fs.mkdirSync(testDir, { recursive: true });
+    vi.spyOn(paths, "writeQueuePath").mockReturnValue(queuePath);
+    vi.spyOn(os, "homedir").mockReturnValue(testDir);
+    writeFavoriteLevels();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true });
+  });
+
+  it("queues and dequeues write spawns in FIFO order", async () => {
+    const first = await enqueueWriteSpawn("team", {
+      id: "first",
+      name: "writer-a",
+      prompt: "A",
+      cwd: testDir,
+      modelSlot: "writing-basic",
+      requestedAt: 1,
+    });
+    const second = await enqueueWriteSpawn("team", {
+      id: "second",
+      name: "writer-b",
+      prompt: "B",
+      cwd: testDir,
+      modelSlot: "writing-hard",
+      requestedAt: 2,
+    });
+
+    expect((await listWriteQueue("team")).map(item => item.id)).toEqual([first.id, second.id]);
+    expect((await dequeueWriteSpawn("team"))?.id).toBe("first");
+    expect((await dequeueWriteSpawn("team"))?.id).toBe("second");
+    expect(await dequeueWriteSpawn("team")).toBeNull();
+  });
+
+  it("handles a high configured writer capacity without dropping order or metadata", async () => {
+    const enqueueStartedAt = Date.now();
+    await Promise.all(Array.from({ length: HIGH_VOLUME_WRITER_COUNT }, (_value, index) => (
+      enqueueWriteSpawn("team", highVolumeWriteSpawn(index))
+    )));
+    const enqueueMs = Date.now() - enqueueStartedAt;
+
+    const queue = await listWriteQueue("team");
+    expect(queue).toHaveLength(HIGH_VOLUME_WRITER_COUNT);
+    expect(queue.slice(0, 3).map(item => item.id)).toEqual([
+      highVolumeWriterId(0),
+      highVolumeWriterId(1),
+      highVolumeWriterId(2),
+    ]);
+    expect(queue.at(-1)).toMatchObject({
+      id: highVolumeWriterId(HIGH_VOLUME_WRITER_COUNT - 1),
+      name: highVolumeWriterId(HIGH_VOLUME_WRITER_COUNT - 1),
+      requestedAt: HIGH_VOLUME_WRITER_COUNT,
+      metadata: { fanout: HIGH_VOLUME_WRITER_COUNT },
+    });
+
+    const middleIndex = Math.floor(HIGH_VOLUME_WRITER_COUNT / 2);
+    const middle = await findQueuedWriteSpawn("team", {
+      operationId: `scale-op-${String(middleIndex).padStart(3, "0")}`,
+      workflowRunId: "scale-run",
+    });
+    expect(middle).toMatchObject({
+      id: highVolumeWriterId(middleIndex),
+      metadata: { slot: middleIndex, fanout: HIGH_VOLUME_WRITER_COUNT },
+    });
+    expect(enqueueMs).toBeLessThan(HIGH_VOLUME_STAGE_BUDGET_MS);
+
+    const dequeueStartedAt = Date.now();
+    const drainedIds: string[] = [];
+    for (let index = 0; index < HIGH_VOLUME_WRITER_COUNT; index++) {
+      const queued = await dequeueWriteSpawn("team");
+      expect(queued).not.toBeNull();
+      drainedIds.push(queued!.id);
+    }
+    const dequeueMs = Date.now() - dequeueStartedAt;
+
+    expect(drainedIds[0]).toBe(highVolumeWriterId(0));
+    expect(drainedIds.at(-1)).toBe(highVolumeWriterId(HIGH_VOLUME_WRITER_COUNT - 1));
+    expect(await dequeueWriteSpawn("team")).toBeNull();
+    expect(dequeueMs).toBeLessThan(HIGH_VOLUME_STAGE_BUDGET_MS);
+  }, HIGH_VOLUME_TEST_TIMEOUT_MS);
+
+  it("deduplicates concurrent queued writers by name under the queue lock", async () => {
+    const results = await Promise.all(Array.from({ length: 50 }, (_value, index) => (
+      enqueueWriteSpawn("team", {
+        id: `duplicate-${index}`,
+        name: "writer-a",
+        prompt: `work ${index}`,
+        cwd: testDir,
+        modelSlot: "writing-basic",
+      })
+    )));
+
+    const queue = await listWriteQueue("team");
+    expect(queue).toHaveLength(1);
+    expect(new Set(results.map(item => item.id))).toEqual(new Set([queue[0].id]));
+  });
+
+  it("dequeues batches atomically without duplicating or dropping concurrent drains", async () => {
+    for (let index = 0; index < 10; index++) {
+      await enqueueWriteSpawn("team", highVolumeWriteSpawn(index));
+    }
+
+    const [first, second] = await Promise.all([
+      dequeueWriteSpawns("team", 7),
+      dequeueWriteSpawns("team", 7),
+    ]);
+    const drainedIds = [...first, ...second].map(item => item.id);
+
+    expect(drainedIds).toHaveLength(10);
+    expect(new Set(drainedIds).size).toBe(10);
+    expect(drainedIds.sort()).toEqual(Array.from({ length: 10 }, (_value, index) => highVolumeWriterId(index)).sort());
+    expect(await listWriteQueue("team")).toEqual([]);
+  });
+
+  it("cancels a queued writer by id", async () => {
+    await enqueueWriteSpawn("team", {
+      id: "keep",
+      name: "writer-a",
+      prompt: "A",
+      cwd: testDir,
+      modelSlot: "writing-basic",
+    });
+    const canceled = await enqueueWriteSpawn("team", {
+      id: "cancel-me",
+      name: "writer-b",
+      prompt: "B",
+      cwd: testDir,
+      modelSlot: "writing-hard",
+    });
+
+    expect(await cancelQueuedWriteSpawn("team", canceled.id)).toEqual(canceled);
+    expect((await listWriteQueue("team")).map(item => item.id)).toEqual(["keep"]);
+    expect(await cancelQueuedWriteSpawn("team", "missing")).toBeNull();
+  });
+
+  it("removes all queued writers by teammate name, including legacy duplicates", async () => {
+    fs.writeFileSync(queuePath, JSON.stringify([
+      { id: "one", name: "writer-a", prompt: "A", cwd: testDir, modelSlot: "writing-basic", requestedAt: 1 },
+      { id: "two", name: "writer-a", prompt: "B", cwd: testDir, modelSlot: "writing-hard", requestedAt: 2 },
+      { id: "three", name: "writer-b", prompt: "C", cwd: testDir, modelSlot: "writing-basic", requestedAt: 3 },
+    ]));
+
+    expect((await removeQueuedWriteSpawnsByName("team", "writer-a")).map(item => item.id)).toEqual(["one", "two"]);
+    expect((await listWriteQueue("team")).map(item => item.id)).toEqual(["three"]);
+  });
+
+  it("uses canonical write-* intent-tier wording for read-tier validation failures", () => {
+    expect(() => queuedWriteSpawnToMember("team", {
+      id: "queued-read",
+      name: "reader-a",
+      prompt: "Inspect it",
+      cwd: testDir,
+      modelSlot: "read-review",
+      requestedAt: 1,
+    })).toThrow(
+      "Queued writer reader-a requires a write-* intent tier configured via /agents-favorite-models, got read-review."
+    );
+  });
+
+  it("converts a queued spawn into a write member", () => {
+    const member = queuedWriteSpawnToMember("team", {
+      id: "queued",
+      name: "writer-a",
+      prompt: "Implement it",
+      cwd: testDir,
+      category: "feature",
+      modelSlot: "writing-hard",
+      planModeRequired: true,
+      requestedAt: 1,
+    });
+
+    expect(member).toMatchObject({
+      agentId: "writer-a@team",
+      name: "writer-a",
+      agentType: "teammate",
+      role: "write",
+      category: "feature",
+      model: "provider/model",
+      modelSlot: "write-system",
+      cwd: testDir,
+      prompt: "Implement it",
+      color: "blue",
+      thinking: "xhigh",
+      planModeRequired: true,
+      tmuxPaneId: "",
+    });
+    expect(member.joinedAt).toEqual(expect.any(Number));
+  });
+});