pi-extended-teams 2.1.16

package/README.md

@@ -0,0 +1,105 @@
+# pi-extended-teams
+
+**A control-first subagent system for Pi.**
+
+pi-extended-teams lets the lead split work into bounded lanes, watch agents live, steer or stop them, and receive their reports. The lead still makes the final call.
+
+Read agents are the default. Edit agents are opt-in and should own isolated files.
+
+[![Three agents working in parallel inside Pi](assets/pi-extended-teams-in-action.png)](assets/pi-extended-teams-in-action.png)
+
+## Install and run
+
+Install from GitHub:
+
+```bash
+pi install git:github.com/dantetekanem/pi-extended-teams
+```
+
+Run `/agents-favorite-models` once in Pi and choose a model and thinking level for each intent tier.
+
+Then ask for help naturally:
+
+```text
+Review the current changes with separate agents for correctness, test gaps, and security. Give me the evidence so I can make the final call.
+```
+
+The current Pi session becomes the agent group automatically. There is no separate setup step.
+
+## How it works
+
+- Read and edit agents run in-process and stay connected to the current Pi session.
+- The activity card shows progress, intent tier, elapsed time, tokens, and tool activity.
+- You can open an agent's transcript, send it a message, or stop it.
+- Completed reports return to the lead automatically and remain recoverable when needed.
+- Every spawn uses a configured intent tier instead of ad hoc model settings.
+- Edit agents can claim isolated files. Claims coordinate cooperative agents; they are not access control.
+- Lazy session context and nested read helpers are available when a bounded task needs them.
+
+This works well for multi-angle code review, root-cause investigation, parallel verification, repository mapping, and one narrow edit that can stay separate from the lead's work.
+
+## Live control
+
+With the editor empty, press Down to open agent navigation. Use Down/Up to move, `l` to expand large tool logs, `m` to message an agent, `x` to stop it, and Escape to return.
+
+[![Inspecting and messaging a running agent](assets/pi-extended-teams-agent-navigation.png)](assets/pi-extended-teams-agent-navigation.png)
+
+Completed reports wake the lead automatically. Do not poll with sleeps, loops, or repeated status checks. Use `check_teammate` only when one agent appears unhealthy or a persisted report needs recovery.
+
+The lead owns decomposition, integration, and acceptance. Pi packages and spawned agents run with your system permissions, so review project-local instructions and configuration through Pi's normal trust flow.
+
+## Intent tiers
+
+Every spawn uses a configured `model_slot`:
+
+| Tier | Use it for |
+| --- | --- |
+| `read-collect` | Bounded facts, logs, inventories, or test output. |
+| `read-review` | Normal review, verification, and test-gap work. |
+| `read-analyze` | Root-cause analysis across connected evidence. |
+| `read-critical` | Rare high-stakes security, architecture, concurrency, migration, or data reasoning. |
+| `write-patch` | A narrow documentation, config, fixture, or bug fix. |
+| `write-feature` | A bounded feature with a known design. |
+| `write-system` | A cross-cutting integration or refactor inside claimed files. |
+| `write-critical` | Rare high-risk security, concurrency, recovery, migration, or data-integrity work. |
+
+`read-review` is the normal read default. Legacy tier names remain accepted for this minor release, but new prompts should use the canonical names above.
+
+## Explicit spawning
+
+Pi can choose when delegation helps, or you can call the tools directly:
+
+```text
+spawn_swarm_agents({
+  defaults: { model_slot: "read-review" },
+  agents: [
+    { name: "correctness", prompt: "Review the diff for concrete correctness risks. Do not edit." },
+    { name: "tests", prompt: "Find missing regression coverage with file and line evidence. Do not edit." }
+  ]
+})
+```
+
+For an edit, choose a write tier and name the files it may claim. Never run overlapping writers against the same paths.
+
+## Configuration
+
+Global settings live at `~/.pi/agent/pi-extended-teams/settings.json`. Project overrides live at `.pi/pi-extended-teams.json`. Favorite intent tiers are global so `/agents-favorite-models` and spawning use the same choices.
+
+Spawned sessions are private by default under `~/.pi/teams/<team>/agent-sessions/` and stay out of Pi's normal `/resume` picker.
+
+## Development
+
+```bash
+pnpm typecheck
+pnpm test:focused
+```
+
+## Credits
+
+pi-extended-teams is based on [pi-teams](https://github.com/burggraf/pi-teams). This fork focuses on session-connected agents, live control, and a smaller public tool surface.
+
+The broader coordination lineage includes [claude-code-teams-mcp](https://github.com/cs50victor/claude-code-teams-mcp).
+
+## License
+
+MIT

package/extensions/agents/read-agent-report.ts

@@ -0,0 +1,181 @@
+import fs from "node:fs";
+import type { AgentReportSource } from "../runtime/types";
+import { getLastAssistantText } from "../ui/renderers";
+import type { SubmittedAgentReport } from "../tools/agent-communication-tools";
+
+export const EMPTY_REPORT_RECOVERY_PROMPT = [
+  "Your previous turn ended without a usable final report.",
+  "Do not perform more investigation or edits.",
+  "Using only the evidence already gathered in this session, call report_and_exit now with the complete non-empty deliverable requested by the original assignment.",
+  "If the assignment could not be completed, call report_and_exit with a non-empty blocker or failure report explaining why.",
+].join(" ");
+
+export interface ResolvedReadAgentReport {
+  report?: string;
+  summary?: string;
+  source?: AgentReportSource;
+  terminalFailure?: string;
+  recoveryReason?: string;
+}
+
+export interface PersistedReadAgentMessages {
+  messages: any[];
+  error?: string;
+}
+
+export class ReadAgentReportUnavailableError extends Error {
+  readonly reportSource = "irrecoverable-empty" as const;
+
+  constructor(
+    message: string,
+    readonly recoveryAttempted: boolean,
+    readonly recoverySessionId?: string,
+    readonly recoverySessionFile?: string,
+  ) {
+    super(message);
+    this.name = "ReadAgentReportUnavailableError";
+  }
+}
+
+export function nonEmptyReportText(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  return text || undefined;
+}
+
+function getAcceptedReportToolSubmission(messages: any[]): SubmittedAgentReport | undefined {
+  const acceptedToolCallIds = new Set<string>();
+  for (const message of messages || []) {
+    if (
+      message?.role === "toolResult"
+      && message.toolName === "report_and_exit"
+      && message.details?.accepted === true
+      && typeof message.toolCallId === "string"
+    ) {
+      acceptedToolCallIds.add(message.toolCallId);
+    }
+  }
+  if (acceptedToolCallIds.size === 0) return undefined;
+
+  for (let messageIndex = messages.length - 1; messageIndex >= 0; messageIndex--) {
+    const message = messages[messageIndex];
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+    for (let partIndex = message.content.length - 1; partIndex >= 0; partIndex--) {
+      const part = message.content[partIndex];
+      if (
+        part?.type !== "toolCall"
+        || part.name !== "report_and_exit"
+        || !acceptedToolCallIds.has(part.id)
+      ) continue;
+      const content = nonEmptyReportText(part.arguments?.content);
+      if (!content) continue;
+      return {
+        content,
+        summary: nonEmptyReportText(part.arguments?.summary),
+      };
+    }
+  }
+  return undefined;
+}
+
+function getLastAssistantMessage(messages: any[]): any | undefined {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (messages[index]?.role === "assistant") return messages[index];
+  }
+  return undefined;
+}
+
+function terminalAssistantState(messages: any[]): { failure?: string; recoveryReason?: string } {
+  const message = getLastAssistantMessage(messages);
+  if (!message) return {};
+  const stopReason = typeof message.stopReason === "string" ? message.stopReason : undefined;
+  const errorMessage = nonEmptyReportText(message.errorMessage);
+  if (stopReason === "error" || stopReason === "aborted") {
+    return {
+      failure: `The final assistant response ended with stopReason=${stopReason}${errorMessage ? `: ${errorMessage}` : "."}`,
+    };
+  }
+  if (stopReason === "length") {
+    return { recoveryReason: "The final assistant response reached its output limit before producing a usable report." };
+  }
+  return {};
+}
+
+export function persistedSessionMessages(
+  SessionManager: any,
+  sessionFile: string | undefined,
+): PersistedReadAgentMessages {
+  if (!sessionFile || !fs.existsSync(sessionFile)) return { messages: [] };
+  try {
+    const entries = SessionManager.open(sessionFile).getEntries();
+    return {
+      messages: entries
+        .filter((entry: any) => entry?.type === "message" && entry.message)
+        .map((entry: any) => entry.message),
+    };
+  } catch (error) {
+    return { messages: [], error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export function resolveReadAgentReport(
+  submittedFinalReport: SubmittedAgentReport | undefined,
+  immediateMessages: any[],
+  persistedMessages: any[],
+): ResolvedReadAgentReport {
+  const submittedContent = nonEmptyReportText(submittedFinalReport?.content);
+  if (submittedContent) {
+    return {
+      report: submittedContent,
+      summary: nonEmptyReportText(submittedFinalReport?.summary),
+      source: "report_and_exit",
+    };
+  }
+
+  const immediateToolReport = getAcceptedReportToolSubmission(immediateMessages);
+  if (immediateToolReport) {
+    return { report: immediateToolReport.content, summary: immediateToolReport.summary, source: "report_and_exit" };
+  }
+  const persistedToolReport = getAcceptedReportToolSubmission(persistedMessages);
+  if (persistedToolReport) {
+    return {
+      report: persistedToolReport.content,
+      summary: persistedToolReport.summary,
+      source: "persisted-report_and_exit",
+    };
+  }
+
+  const terminal = terminalAssistantState(immediateMessages.length > 0 ? immediateMessages : persistedMessages);
+  if (terminal.failure) return { terminalFailure: terminal.failure };
+  if (terminal.recoveryReason) return { recoveryReason: terminal.recoveryReason };
+
+  const immediateText = getLastAssistantText(immediateMessages);
+  if (immediateText) return { report: immediateText, source: "assistant-text" };
+  const persistedText = getLastAssistantText(persistedMessages);
+  if (persistedText) return { report: persistedText, source: "persisted-assistant-text" };
+  return {};
+}
+
+export function readAgentRecoveryReference(
+  teamName: string,
+  agentName: string,
+  runId: string,
+  sessionManager: any,
+): { sessionId?: string; sessionFile?: string; durableFile: boolean; pointer: string; guidance: string } {
+  const sessionId = nonEmptyReportText(sessionManager?.getSessionId?.());
+  const sessionFile = nonEmptyReportText(sessionManager?.getSessionFile?.());
+  const durableFile = !!sessionFile && fs.existsSync(sessionFile);
+  const pointer = [
+    "pi-child-session/v1",
+    `team=${JSON.stringify(teamName)}`,
+    `agent=${JSON.stringify(agentName)}`,
+    `lifecycleRunId=${JSON.stringify(runId)}`,
+    `sessionId=${JSON.stringify(sessionId ?? "unavailable")}`,
+    `sessionFile=${JSON.stringify(sessionFile ?? "unavailable")}`,
+    `durableFile=${durableFile}`,
+  ].join(" ");
+  const guidance = durableFile
+    ? `Retrieve the child transcript with the read tool at ${JSON.stringify(sessionFile)} or open it with SessionManager.open(${JSON.stringify(sessionFile)}). Inspect newest message entries for an accepted report_and_exit call and assistant text.`
+    : "No child JSONL file was materialized; use the team, agent, lifecycle run, and session identifiers above to correlate runtime and report-event diagnostics.";
+  return { sessionId, sessionFile, durableFile, pointer, guidance };
+}