pi-extended-teams 2.2.6 → 2.2.7

package/README.md

@@ -55,6 +55,8 @@ This works well for multi-angle code review, root-cause investigation, parallel
 
 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, `i` to interrupt its currently running tool command, `x` to stop the whole agent, and Escape to return.
 
+Inside Herdr, press `h` in an ordinary direct agent's preview to move it into a focused sibling Pi pane in the same workspace. Its conversation and team communication continue there. Nested helpers and delegation-enabled or workflow agents are excluded.
+
 Scroll the transcript with Page Up/Page Down or the mouse wheel, including under Herdr. Press End or scroll back to the bottom to follow new output.
 
 The lead can invoke the same command-only behavior with `interrupt_teammate({ agent_name: "agent" })`. It keeps the agent's session, task context, and file claims intact so you can send follow-up work. In-process cancellation is cooperative and may report that it is still pending; for tmux-backed agents, success means Pi's Escape key was delivered, not that command settlement was independently confirmed.

package/docs/access.md

@@ -8,13 +8,13 @@
 - Write teammates start a separate Pi process in a tmux pane. The extension builds and runs the local Pi launch command with the teammate's working directory, model and thinking configuration, selected extensions, and `PI_TEAM_NAME`, `PI_AGENT_NAME`, and `PI_LIFECYCLE_RUN_ID` environment variables.
 - Before launching a write teammate, the extension runs a bounded local `pi models --all` preflight through `sh -c` to determine whether the configured model is available.
 - On macOS, while at least one write teammate is active, the extension may run `/usr/bin/caffeinate -i -w <lead-pid>` to prevent idle system sleep. It terminates that helper when no write teammates remain or the extension is disposed.
-- In a Herdr session, the extension can invoke the configured `herdr` binary to split, start, and close panes when moving an agent. The binary path defaults to `herdr` and can be set with `HERDR_BIN_PATH`.
+- Inside Herdr, pressing `h` can move an eligible in-process agent into a sibling Pi pane. The extension calls the `herdr` executable to split, run, focus, or close that pane.
 
 ## Files and local state
 
 The extension reads settings from `~/.pi/agent/pi-extended-teams/settings.json` and `<project>/.pi/pi-extended-teams.json`. Model-provider compatibility also reads the legacy `~/.pi/pi-extended-teams.json` path. Predefined agents can be read from `~/.pi/agent/agents/` and `<project>/.pi/agents/`; team templates can be read or written at `~/.pi/teams.yaml`, `~/.pi/agent/teams.yaml`, and `<project>/.pi/teams.yaml`.
 
-For a team named `<team>`, coordination state is stored under `~/.pi/teams/<team>/`. This includes `config.json`, inboxes, runtime status, session-context references, lifecycle quarantine and tombstones, file claims, write and read-helper queues, shared memory, report events, lead-session metadata, debug logs, and private child transcripts under `agent-sessions/`. Task records are stored under `~/.pi/tasks/<team>/`, and agent reports may also be written under `~/.pi/agent/reports/`. Cleanup removes lifecycle and queue files when they are no longer needed.
+For a team named `<team>`, coordination state is stored under `~/.pi/teams/<team>/`. This includes `config.json`, inboxes, runtime status, session-context references, lifecycle quarantine and tombstones, file claims, write and read-helper queues, shared memory, report events, lead-session metadata, debug logs, and private child transcripts and handoff prompt snapshots under `agent-sessions/`. Task records are stored under `~/.pi/tasks/<team>/`, and agent reports may also be written under `~/.pi/agent/reports/`. Cleanup removes lifecycle and queue files when they are no longer needed.
 
 The extension reads project extension sources only when Pi marks the same working directory trusted. Teammates receive the working directory supplied at spawn time. A write teammate can use any filesystem access granted to its child Pi process and enabled tools. A read teammate's tools are restricted by the extension, but it still receives prompt and project context supplied by the lead.
 

package/extensions/agents/read-agent.ts

@@ -1,4 +1,9 @@
 import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { buildPiCommand, getPiLaunchCommand, shellQuote } from "../internal/pi-command";
+import { herdrCommand } from "../runtime/herdr";
 import * as runtime from "../../src/utils/runtime";
 import * as teams from "../../src/utils/teams";
 import * as messaging from "../../src/utils/messaging";
@@ -12,7 +17,7 @@ import { isPiPromptPlanningMember, shouldSuppressLeadReportInjection } from "../
 import { canonicalPersistedModelSlot, loadSettings, requireFavoriteModelLevel } from "../../src/utils/settings";
 import { parseQualifiedModel } from "../../src/utils/model-resolution";
 import { closePersistedRecipient } from "../team/recipient-closure";
-import { generateExtensionInstanceId, generateLifecycleRunId } from "../../src/utils/lifecycle-tombstone";
+import { generateExtensionInstanceId, generateLifecycleRunId, withLifecycleTombstoneLock } from "../../src/utils/lifecycle-tombstone";
 import { createLifecycleRuntime, type ShutdownTeammateOptions } from "../team/lifecycle";
 import {
   createSpawnResourcePlan,
@@ -634,6 +639,7 @@ export async function runReadAgentInProcess(
     getTeamName: () => readTeamName,
   }).shutdownTeammate;
 
+  let handoffRequested = false;
   let submittedFinalReport: SubmittedAgentReport | undefined;
   let finalReportSubmissionInProgress = false;
   let childSessionManager: any;
@@ -660,6 +666,7 @@ export async function runReadAgentInProcess(
   const closeRecipient = async (): Promise<ReadAgentDeliveryCloseResult> => {
     if (pendingChildParent) pendingChildController?.cancelParent(pendingChildParent);
     const deliveryClose = closeReadAgentMessageDelivery(state);
+    if (handoffRequested) return deliveryClose;
     if (!state.recipientClosurePromise) {
       state.recipientClosurePromise = closePersistedRecipient(
         readTeamName,
@@ -959,7 +966,7 @@ export async function runReadAgentInProcess(
     } as Parameters<typeof createAgentSession>[0] & { modelRuntime?: unknown });
 
     state.session = session;
-    installReadAgentSessionLifecycle(session);
+    const sessionLifecycle = installReadAgentSessionLifecycle(session);
     try {
       if (typeof session.bindExtensions === "function") {
         await (session.bindExtensions as (bindings: { mode: "print" }) => Promise<void>)({ mode: "print" });
@@ -973,6 +980,96 @@ export async function runReadAgentInProcess(
       if (state.teardownState !== "persistence_failed") await state.teardownPromise;
       return;
     }
+    if (process.env.HERDR_ENV === "1" && (member.delegationDepth ?? 0) === 0
+      && !member.requestedBy && !member.parentAgentName && !member.allowNestedReadAgents
+      && !shouldSuppressLeadReportInjection(member)) {
+      let moving: Promise<void> | undefined;
+      let paneId: string | undefined;
+      let command = "";
+      let queued: string[] = [];
+      let released = false;
+      const release = Promise.all([finished, sessionLifecycle.finalized]).then(() => {
+        if (handoffRequested) { state.session = undefined; released = true; }
+      });
+      void release.catch(() => {});
+      const recordPane = (id: string | undefined) => withLifecycleTombstoneLock(readTeamName, member.name, async lock => {
+        const current = (await teams.readConfig(readTeamName)).members.find(item => item.name === member.name);
+        if (!current || current.lifecycleRunId !== state.runId || current.isActive === false || lock.read().status !== "absent") {
+          throw new Error("The agent is no longer available to move.");
+        }
+        await teams.updateMember(readTeamName, member.name, { herdrPaneId: id, tmuxPaneId: "" });
+      });
+      state.moveToHerdr = () => moving ??= (async () => {
+        if (!options.isCurrentReadAgentRun(key, state) || (!handoffRequested && !state.acceptingMessages)) {
+          throw new Error("The agent is already finishing.");
+        }
+        if (handoffRequested && !released) throw new Error("The current operation is still stopping. Try h after it settles.");
+        if (paneId) { herdrCommand("pane", "close", paneId); await recordPane(undefined); paneId = undefined; }
+        const sessionFile = childSessionManager.getSessionFile();
+        if (!sessionFile || !fs.existsSync(sessionFile)) throw new Error("The agent has no saved session yet.");
+        if (!handoffRequested) {
+          const promptDir = privateSessionDirectory ?? preparePrivateAgentSessionDirectory(readTeamName, member.name, state.runId);
+          const promptFile = path.join(promptDir, "herdr-system-prompt.txt");
+          fs.writeFileSync(promptFile, session.agent.state.systemPrompt.replace("running in-process so the lead can follow and control you from Pi", "running in a Herdr pane"), { mode: 0o600 });
+          const tools = session.agent.state.tools.map(tool => tool.name).join(",");
+          const identity = {
+            HOME: os.homedir(), PI_CODING_AGENT_DIR: agentDir,
+            PI_AGENT_NAME: member.name, PI_TEAM_NAME: readTeamName, PI_LIFECYCLE_RUN_ID: state.runId,
+            PI_EXTENDED_TEAMS_HERDR_RESUME: "1",
+          };
+          const currentModel = session.model ?? model;
+          const launch = buildPiCommand(getPiLaunchCommand(), `${currentModel.provider}/${currentModel.id}`,
+            session.thinkingLevel ?? member.thinking, resourcePlan.extensionPaths,
+            resourcePlan.trust.projectTrusted, resourcePlan.selfExtensionPath);
+          command = [
+            "env", ...Object.entries(identity).map(([name, value]) => `${name}=${shellQuote(value)}`), launch,
+            "--session", shellQuote(sessionFile), "--tools", shellQuote(tools), "--system-prompt", shellQuote(promptFile),
+          ].join(" ");
+          // Keep fresh-shell input below the PTY line limit without shortening the launch arguments.
+          const launchFile = path.join(promptDir, "herdr-launch.sh");
+          fs.writeFileSync(launchFile, `exec ${command}\n`, { mode: 0o600 });
+          command = `/bin/sh ${shellQuote(launchFile)}`;
+        }
+        paneId = JSON.parse(herdrCommand("pane", "split", "--current", "--direction", "right", "--cwd", member.cwd, "--focus")).result?.pane?.pane_id;
+        if (typeof paneId !== "string" || !paneId) throw new Error("Herdr did not return a pane ID.");
+        try {
+          if (!handoffRequested) {
+            handoffRequested = true;
+            state.stopRequested = true;
+            const delivery = closeReadAgentMessageDelivery(state);
+            const pending = session.clearQueue();
+            queued = [...pending.steering, ...pending.followUp];
+            signalReadAgentWake(state);
+            const shutdown = await sessionLifecycle.requestShutdown("resume", delivery.rawDeliverySettlement);
+            if (shutdown.status !== "settled" || shutdown.abort !== "settled" || shutdown.dispose !== "settled") {
+              throw new Error("The current operation has not stopped. Try h after it settles.");
+            }
+            await release;
+          }
+          if (queued.length) {
+            SessionManager.open(sessionFile).appendMessage({ role: "user", content: queued.join("\n\n"), timestamp: Date.now() });
+            queued = [];
+          }
+          const previousPid = (await runtime.readRuntimeStatus(readTeamName, member.name))?.pid;
+          await recordPane(paneId);
+          herdrCommand("pane", "run", paneId, command);
+          const deadline = Date.now() + 10000;
+          for (;;) {
+            const status = await runtime.readRuntimeStatus(readTeamName, member.name);
+            if (status?.lifecycleRunId === state.runId && status.pid && status.pid !== previousPid && status.pid !== process.pid) break;
+            if (Date.now() >= deadline) throw new Error("Pi did not resume. The saved session is retained; h can retry.");
+            await new Promise(resolve => setTimeout(resolve, 50));
+          }
+          if (options.isCurrentReadAgentRun(key, state)) options.runningReadAgents.delete(key);
+          options.renderReadAgentStatus();
+        } catch (error) {
+          herdrCommand("pane", "close", paneId);
+          await recordPane(undefined);
+          paneId = undefined;
+          throw error;
+        }
+      })().catch(error => { moving = undefined; throw error; });
+    }
     markReadAgentActivity(state, "started", "thinking");
     options.renderReadAgentStatus();
 
@@ -1262,6 +1359,7 @@ export async function runReadAgentInProcess(
     if (state.heartbeatTimer) clearInterval(state.heartbeatTimer);
     state.heartbeatTimer = undefined;
     closeReadAgentMessageDelivery(state);
+    if (handoffRequested) { state.resolveFinished?.(); return; }
     const teardown = await shutdownTeammate(readTeamName, member, { reason: "quit" });
     if (pendingChildController && pendingChildParent) {
       pendingChildController.forgetParent(pendingChildParent);

package/extensions/events/register-events.ts

@@ -220,10 +220,14 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
       }
 
       scheduleTeammateOneShot(() => {
-        options.quietTrigger("read_inbox to get your instructions, then begin your work.");
+        options.quietTrigger(process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1"
+          ? "Continue your existing assignment. Read any new inbox messages, then finish and report_and_exit from this pane."
+          : "read_inbox to get your instructions, then begin your work.");
       }, 1000);
 
       if (teamName) {
+        const herdrResume = process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1";
+        let notifiedInbox: string | undefined;
         let wakeInFlight = false;
         const wakeIfUnread = async () => {
           if (teammateInboxDisposed) return;
@@ -232,7 +236,7 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
             scheduleTeammateInboxWake(250);
             return;
           }
-          if (!ctx.isIdle()) {
+          if (!ctx.isIdle() && !herdrResume) {
             teammatePendingInboxWake = true;
             scheduleTeammateInboxWake(250);
             return;
@@ -246,7 +250,15 @@ export function registerExtensionEvents(pi: any, options: RegisterEventsOptions)
               lastHeartbeatAt: Date.now(),
             });
             if (unread.length > 0) {
-              options.quietTrigger(`You have ${unread.length} new inbox message(s). Read them with read_inbox and act.`);
+              const content = `You have ${unread.length} new inbox message(s). Read them with read_inbox and act.`;
+              if (herdrResume) {
+                const inboxVersion = JSON.stringify(unread);
+                if (inboxVersion !== notifiedInbox) {
+                  pi.sendMessage({ customType: "pi-extended-teams-wake", content, display: false },
+                    { triggerTurn: true, deliverAs: "steer" });
+                  notifiedInbox = inboxVersion;
+                }
+              } else options.quietTrigger(content);
             }
           } catch (e) {
             if (!teammateInboxDisposed) {

package/extensions/runtime/herdr.ts

@@ -0,0 +1,13 @@
+import { spawnSync } from "node:child_process";
+
+export function herdrCommand(...args: string[]): string {
+  if (process.env.HERDR_ENV !== "1") throw new Error("This action requires Herdr.");
+  const result = spawnSync("herdr", args, { encoding: "utf8", timeout: 5000 });
+  if (result.status !== 0) {
+    let code: string | undefined;
+    try { code = JSON.parse(result.stderr).error?.code; } catch { /* Non-JSON CLI failure. */ }
+    if (args[0] === "pane" && args[1] === "close" && code === "pane_not_found") return "";
+    throw new Error(result.stderr || result.error?.message || "Herdr command failed.");
+  }
+  return result.stdout;
+}

package/extensions/runtime/types.ts

@@ -47,6 +47,7 @@ export interface RunningReadAgent extends ManagedReadAgentLifecycleState {
   /** Fail finalization closed so runtime, member, fence, and transcript remain recoverable. */
   finalizationBlockedReason?: string;
   session?: AgentSession;
+  moveToHerdr?(): Promise<void>;
   finished?: Promise<void>;
 }
 

package/extensions/team/lifecycle.ts

@@ -20,7 +20,8 @@ import {
   type ReadAgentTeardownResult,
 } from "../agents/read-agent-session-lifecycle";
 import { releaseAllClaimsForAgent } from "./roster";
-import { cleanupPidFileProcess } from "../internal/session-files";
+import { cleanupPidFileProcess, unlinkPidFile } from "../internal/session-files";
+import { herdrCommand } from "../runtime/herdr";
 import { closePersistedRecipient } from "./recipient-closure";
 import { cleanupPrivateAgentSessionDirectory } from "../internal/agent-session-files";
 
@@ -65,7 +66,10 @@ export function createLifecycleRuntime(options: LifecycleRuntimeOptions) {
   async function finalizeTeammateRuntime(teamName: string, member: Member, expectedRunId: string): Promise<void> {
     const pidFile = path.join(paths.teamDir(teamName), `${member.name}.pid`);
     const pidFileExisted = fs.existsSync(pidFile);
-    const pidCleanup = cleanupPidFileProcess(pidFile, { skipPid: process.pid });
+    if (member.herdrPaneId) herdrCommand("pane", "close", member.herdrPaneId);
+    const pidCleanup = member.herdrPaneId
+      ? { pid: undefined, killError: undefined, unlinked: !pidFileExisted || unlinkPidFile(pidFile) }
+      : cleanupPidFileProcess(pidFile, { skipPid: process.pid });
     if (pidFileExisted && !pidCleanup.unlinked) {
       throw new Error(`Could not remove pid file for ${member.name}.`);
     }

package/extensions/tools/coordination-tools.ts

@@ -147,6 +147,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, ctx: any) {
       const targetTeamName = requireCurrentSession(options);
       if (!options.isTeammate) throw new Error("report_and_exit is only available to spawned agents.");
+      if (process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1" && !params.content.trim()) throw new Error("Final report content must not be empty.");
 
       const config = await teams.readConfig(targetTeamName);
       const member = config.members.find(m => m.name === options.agentName);
@@ -271,6 +272,7 @@ export function registerCoordinationTools(pi: any, options: CoordinationToolsOpt
     async execute(_toolCallId: string, params: any, _signal: AbortSignal, _onUpdate: any, _ctx: any) {
       const targetTeamName = requireCurrentSession(options);
       const targetAgent = params.agent_name || options.agentName;
+      if (process.env.PI_EXTENDED_TEAMS_HERDR_RESUME === "1" && targetAgent !== options.agentName) throw new Error("A resumed subagent can only read its own inbox.");
       const markAsRead = params.mark_as_read !== false;
       const unreadOnly = params.unread_only !== false;
       const msgs = await messaging.readInbox(targetTeamName, targetAgent, unreadOnly, markAsRead);

package/extensions/ui/agent-follow-view.ts

@@ -605,11 +605,12 @@ export function createAgentFollowComponent(
       const logAction = expandLargeToolResults ? "l collapse logs" : "l expand logs";
       const messageAction = options.sendMessage ? " · m message" : "";
       const interruptAction = options.interruptAgent ? " · i interrupt" : "";
-      const help = composingMessage
+      const herdrAction = process.env.HERDR_ENV === "1" && agent.moveToHerdr ? " · h Herdr" : "";
+      const help = messageStatus && !options.sendMessage ? messageStatus : composingMessage
         ? `message ${agent.name} · enter send · esc cancel`
         : agents.length > 1
-          ? `↑ previous/main · ↓ next agent · ←/→ agent · ${logAction}${messageAction}${interruptAction} · x stop · pgup/pgdn scroll · esc main`
-          : `↑/esc main · ${logAction}${messageAction}${interruptAction} · x stop · pgup/pgdn scroll · end follow`;
+          ? `↑ previous/main · ↓ next agent · ←/→ agent · ${logAction}${messageAction}${interruptAction}${herdrAction} · x stop · pgup/pgdn scroll · esc main`
+          : `↑/esc main · ${logAction}${messageAction}${interruptAction}${herdrAction} · x stop · pgup/pgdn scroll · end follow`;
 
       const currentTranscriptWidth = Math.max(20, innerWidth);
       if (transcriptAgent !== agent
@@ -766,6 +767,14 @@ export function createAgentFollowComponent(
         tui.requestRender();
         return;
       }
+      if (data.toLowerCase() === "h" && process.env.HERDR_ENV === "1") {
+        const agent = currentAgent(sortedAgents(), selectedName);
+        if (agent?.moveToHerdr) void agent.moveToHerdr().then(done).catch(error => {
+          messageStatus = sanitizePlainTuiLine(error instanceof Error ? error.message : String(error));
+          tui.requestRender();
+        });
+        return;
+      }
       if (data.toLowerCase() === "i" && options.interruptAgent) {
         const agent = currentAgent(sortedAgents(), selectedName);
         if (!agent || interruptingAgents.has(agent.name)) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extended-teams",
-  "version": "2.2.6",
+  "version": "2.2.7",
   "description": "Control-first, session-connected subagents for Pi with live navigation and intent-tier routing",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "test:focused": "vitest run src/utils/claims.test.ts src/utils/tasks.test.ts src/utils/model-resolution.test.ts src/utils/settings.test.ts src/utils/write-queue.test.ts src/utils/shared-memory.test.ts extensions/index.test.ts extensions/events/register-events.test.ts extensions/internal/session-files.test.ts extensions/team/contracts.test.ts extensions/tools/delegation-guard.test.ts extensions/tools/agent-communication-tools.test.ts extensions/tools/read-helper.test.ts extensions/agents/read-agent.test.ts extensions/agents/write-agent.test.ts extensions/tools/team-tools.read-agent.test.ts",
+    "test:focused": "vitest run src/utils/claims.test.ts src/utils/tasks.test.ts src/utils/model-resolution.test.ts src/utils/settings.test.ts src/utils/write-queue.test.ts src/utils/shared-memory.test.ts extensions/index.test.ts extensions/events/register-events.test.ts extensions/internal/session-files.test.ts extensions/team/contracts.test.ts extensions/tools/delegation-guard.test.ts extensions/tools/agent-communication-tools.test.ts extensions/tools/read-helper.test.ts extensions/agents/read-agent.test.ts extensions/agents/write-agent.test.ts extensions/tools/team-tools.read-agent.test.ts extensions/ui/agent-follow-view.test.ts extensions/tools/coordination-tools.test.ts",
     "build": "tsc --noEmit"
   },
   "main": "extensions/index.ts",

package/src/utils/models.ts

@@ -10,6 +10,7 @@ export interface Member {
   model?: string;
   joinedAt: number;
   tmuxPaneId: string;
+  herdrPaneId?: string;
   windowId?: string;
   cwd: string;
   subscriptions: any[];
@@ -33,7 +34,7 @@ export interface Member {
   parentAgentName?: string;
   /** Runtime-owned parent lifecycle identity for a restricted nested read child. */
   parentLifecycleRunId?: string;
-  /** "read" agents run in-process (no pane); "write" agents spawn in tmux. */
+  /** Tool role; execution may be in-process or in a terminal pane. */
   role?: "read" | "write";
   /** Optional category preset name from settings.json. */
   category?: string;