pi-herdsman 0.21.0 → 0.21.2

package/dist/index.js

@@ -1,7 +1,7 @@
 // extension/index.ts
 import { contentText as contentText5 } from "@earendil-works/pi-ai";
 import {
-  buildSessionProjection as buildSessionProjection2,
+  buildSessionProjection as buildSessionProjection3,
   DynamicBorder,
   getAgentDir as getAgentDir4,
   getSelectListTheme as getSelectListTheme2,
@@ -15,7 +15,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 // package.json
 var package_default = {
   name: "pi-herdsman",
-  version: "0.21.0",
+  version: "0.21.2",
   type: "module",
   description: "Asynchronous Pi subagents and agent fleet orchestration for parallel coding agents with nested delegation, background work, and supervision in herdr.",
   license: "Apache-2.0",
@@ -64,7 +64,7 @@ var package_default = {
   },
   piHerdsman: {
     runtime: {
-      pi: "1.0.1",
+      pi: "1.0.4",
       herdr: {
         version: "0.9.3",
         sha256: {
@@ -93,9 +93,9 @@ var package_default = {
     typebox: "*"
   },
   devDependencies: {
-    "@earendil-works/pi-ai": "1.0.1",
-    "@earendil-works/pi-coding-agent": "1.0.1",
-    "@earendil-works/pi-tui": "1.0.1",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
     esbuild: "^0.28.2",
     typebox: "^1.3.7"
   },
@@ -1579,6 +1579,11 @@ function overrideBodyMode(definition) {
 function normalizedToolNames(tools) {
   return (tools ?? []).flatMap((tool) => tool.split(",")).map((tool) => tool.trim()).filter(Boolean);
 }
+function matchesToolPattern(pattern, name) {
+  if (!pattern.includes("*")) return pattern === name;
+  const source = pattern.split("*").map((part) => part.replace(/[.+?^${}()|[\]\\]/gu, "\\$&")).join(".*");
+  return new RegExp(`^${source}$`, "u").test(name);
+}
 function readOptionalAgentDefinitions(root2) {
   const stats = statSync3(root2, { throwIfNoEntry: false });
   if (!stats) return [];
@@ -1954,33 +1959,41 @@ function agentLaunchArgs(agent, options) {
     }
   }
   if (sharedPromptPath) args.push("--append-system-prompt", sharedPromptPath);
-  if (managedAgent)
-    args.push("--append-system-prompt", `<active_agent name="${agent.name}"/>`);
   const explicitTools = frontmatter.tools !== void 0;
-  const noTools = frontmatter.noTools || explicitTools && frontmatter.tools.length === 0;
+  const configuredTools = normalizedToolNames(frontmatter.tools);
+  const noTools = frontmatter.noTools === true || explicitTools && configuredTools.length === 0;
   if (noTools) args.push("--no-tools");
   if (frontmatter.noBuiltinTools) args.push("--no-builtin-tools");
   const requiredTools = [
     ...managedAgent ? agentDefinitionDelegationEnabled(agent) ? [...AGENT_COORDINATION_TOOLS, "ask_owner"] : ["ask_owner"] : [],
     ...options.requiredTools ?? []
   ].filter((tool, index, all) => all.indexOf(tool) === index);
-  if (managedAgent || requiredTools.length) {
-    if (noTools || explicitTools) {
-      const configuredTools = normalizedToolNames(frontmatter.tools).filter(
-        (tool) => (!managedAgent || tool !== "agent") && !requiredTools.includes(tool)
+  const requiredToolSet = new Set(requiredTools);
+  const excluded = normalizedToolNames(frontmatter.excludeTools).filter((pattern) => !requiredToolSet.has(pattern)).filter((pattern, index, all) => all.indexOf(pattern) === index);
+  for (const pattern of excluded) {
+    if (!pattern.includes("*")) continue;
+    const required = requiredTools.find(
+      (tool) => matchesToolPattern(pattern, tool)
+    );
+    if (required)
+      throw new Error(
+        `agent ${agent.name} excludeTools pattern ${JSON.stringify(pattern)} matches required tool ${JSON.stringify(required)}; required tools cannot be excluded by patterns`
       );
-      const tools = [.../* @__PURE__ */ new Set([...configuredTools, ...requiredTools])];
-      if (tools.length) args.push("--tools", tools.join(","));
+  }
+  if (noTools || explicitTools) {
+    const configured = configuredTools.filter(
+      (tool) => (!managedAgent || tool !== "agent") && !requiredToolSet.has(tool)
+    );
+    const selected = [.../* @__PURE__ */ new Set([...configured, ...requiredTools])];
+    if (selected.length) {
+      if (!selected.some((tool) => tool.startsWith("mcp__"))) {
+        selected.push("mcp__");
+        if (!excluded.includes("mcp__")) excluded.push("mcp__");
+      }
+      args.push("--tools", selected.join(","));
     }
-    const requiredToolSet = new Set(requiredTools);
-    const excluded = normalizedToolNames(frontmatter.excludeTools).filter((tool) => !requiredToolSet.has(tool)).filter((tool, index, all) => all.indexOf(tool) === index);
-    if (excluded.length) args.push("--exclude-tools", excluded.join(","));
-  } else {
-    if (frontmatter.tools?.length)
-      args.push("--tools", frontmatter.tools.join(","));
-    if (frontmatter.excludeTools?.length)
-      args.push("--exclude-tools", frontmatter.excludeTools.join(","));
   }
+  if (excluded.length) args.push("--exclude-tools", excluded.join(","));
   const noSkills = frontmatter.noSkills ?? frontmatter.inheritSkills !== true;
   if (noSkills) args.push("--no-skills");
   for (const skill of frontmatter.skills ?? []) args.push("--skill", skill);
@@ -1989,6 +2002,8 @@ function agentLaunchArgs(agent, options) {
     args.push("--no-extensions");
   for (const extension of frontmatter.extensions ?? [])
     args.push("--extension", extension);
+  if (managedAgent)
+    args.push("--append-system-prompt", `<active_agent name="${agent.name}"/>`);
   return args;
 }
 
@@ -3800,6 +3815,7 @@ async function rollbackHerdrStart(pi, ctx, started, signal) {
 // extension/managed-agent-runtime.ts
 import { isAbsolute as isAbsolute4, resolve as resolve5 } from "node:path";
 import { realpathSync as realpathSync4 } from "node:fs";
+import { buildSessionProjection as buildSessionProjection2 } from "@earendil-works/pi-coding-agent";
 import { contentText as contentText3 } from "@earendil-works/pi-ai";
 
 // extension/agent-controller.ts
@@ -11889,10 +11905,21 @@ function createAgentController(pi, options) {
         } finally {
           resetRelease();
         }
+        let ownerDisplay = "lead";
+        if (scope.kind === "managed-agent") {
+          const definition2 = process.env.PI_HERDSMAN_AGENT_DEFINITION;
+          const parentLabel = process.env.PI_HERDSMAN_LABEL;
+          if (!definition2 || !parentLabel)
+            throw new Error(
+              "Managed-Agent launch is missing its definition or label"
+            );
+          ownerDisplay = displayIdentity(definition2, parentLabel);
+        }
         const env = [
           `PI_HERDSMAN_MAILBOX=${mailbox}`,
           `PI_HERDSMAN_RUN_ID=${runId}`,
           `PI_HERDSMAN_OWNER_SESSION_ID=${owner}`,
+          `PI_HERDSMAN_OWNER_DISPLAY=${ownerDisplay}`,
           `PI_SUBAGENT_PARENT_SESSION=${forwardingSession}`,
           `PI_HERDSMAN_LABEL=${label}`,
           `PI_HERDSMAN_WORKSPACE_ID=${workspaceId}`,
@@ -13527,6 +13554,9 @@ function collectSessionUsage(ctx, ownedChildren, openOwnedSession, leadRoots = [
 import { randomUUID as randomUUID9 } from "node:crypto";
 import { Type as Type2 } from "typebox";
 import { isDeepStrictEqual } from "node:util";
+var DELEGATING_AGENT_ROLE_CHARTER = `## Delegating agent role
+${DELEGATING_AGENT_SCOPE_DESCRIPTION}
+${FILE_HANDOFF_GUIDANCE}`;
 function currentTurnIsSoleToolCall(message, name) {
   const turn = message;
   if (turn?.role !== "assistant" || !Array.isArray(turn.content)) return false;
@@ -13670,6 +13700,7 @@ var AGENT_LABEL_PATTERN2 = /^[a-z][a-z0-9_-]{0,31}$/;
 var RESERVED_PREFIX = "__PI_HERDSMAN_AGENT_V5__:";
 var AGENT_CONTEXT_RETIRED_ENTRY = "pi-herdsman-agent-context-retired";
 var CONTEXT_RETIREMENT_INSTRUCTION = "Context pressure has retired this session. Do not start new work or new agents. Finish the current coherent operation at the next safe point. Avoid nonessential tool calls and validation; perform only what is needed for a reliable handoff. Resolve already-running dependent work, then complete this assignment with a self-contained handoff covering completed work, current state, relevant files, validation performed, unresolved issues, and exact next steps. This session will not be continued or forked.";
+var CONTEXT_RETIREMENT_REMINDER = "This session is retired. Do not start new work or agents. Finish the current assignment and return a self-contained handoff.";
 function createManagedAgentExecutionState() {
   return {
     assignment: void 0,
@@ -14699,7 +14730,9 @@ function registerManagedAgentRuntime(pi, options) {
         const view = await controller.agentSnapshotView(
           ctx,
           scope,
-          controller.sessionSignal()
+          controller.sessionSignal(),
+          true,
+          false
         );
         return buildAgentStatusSnapshot(view, ctx, {
           scope,
@@ -14717,29 +14750,23 @@ function registerManagedAgentRuntime(pi, options) {
     });
   }
   controller?.registerTools(/* @__PURE__ */ new Map());
-  if (delegationEnabled)
-    pi.on("before_agent_start", async (event, ctx) => {
-      const projection = await options.prepareDelegatingStart(ctx);
-      if (projection.supervisorStateMessage)
-        pi.sendMessage(projection.supervisorStateMessage, {
-          triggerTurn: false
-        });
+  pi.on("before_agent_start", (event, ctx) => {
+    const definition = process.env.PI_HERDSMAN_AGENT_DEFINITION;
+    const label = process.env.PI_HERDSMAN_LABEL;
+    event.systemPromptOptions.sections.pi_herdsman_agent = [
+      `identity: ${displayIdentity(definition, label)}`,
+      `direct_owner: ${process.env.PI_HERDSMAN_OWNER_DISPLAY}`
+    ].join("\n");
+    if (delegationEnabled) {
       const roster = startupDefinitionRoster;
       const availableRoster = roster?.sessionId === ctx.sessionManager.getSessionId() ? roster : void 0;
-      return {
-        systemPrompt: `${event.systemPrompt}
-
-${projection.roleCharter}
+      event.systemPromptOptions.sections.delegating_agent_role = DELEGATING_AGENT_ROLE_CHARTER;
+      if (availableRoster)
+        event.systemPromptOptions.sections.agent_definitions = `${JSON.stringify(availableRoster.definitions, null, 2)}
 
-` + (availableRoster ? `## Available agent definitions
-
-<agent_definitions>
-${JSON.stringify(availableRoster.definitions, null, 2)}
-</agent_definitions>
-
-This is the session-start definition snapshot. Use agent_list for live Agent state or to refresh Agent definitions after configuration changes.` : "")
-      };
-    });
+This is the session-start definition snapshot. Use agent_list for live Agent state or to refresh Agent definitions after configuration changes.`;
+    }
+  });
   const execution = createManagedAgentExecutionState();
   const metadataPublisher = createManagedAgentMetadataPublisher(pi);
   const leafStatus = createManagedAgentLeafStatus({
@@ -14876,10 +14903,6 @@ This is the session-start definition snapshot. Use agent_list for live Agent sta
       }
     })
   );
-  registerManagedAgentContextHandlers(pi, {
-    contextRetirementEnabled: () => readConfig().contextRetirement,
-    hasActiveAssignment: () => !!execution.assignment?.activeRequestId
-  });
   const prepareDelegatingRoster = async (ctx) => {
     startupDefinitionRoster = void 0;
     if (!delegationEnabled) return;
@@ -15006,6 +15029,10 @@ This is the session-start definition snapshot. Use agent_list for live Agent sta
       controller.shutdown();
     }
   });
+  registerManagedAgentContextHandlers(pi, {
+    contextRetirementEnabled: () => readConfig().contextRetirement,
+    hasActiveAssignment: () => !!execution.assignment?.activeRequestId
+  });
 }
 function createManagedAgentRequestState(pi, options) {
   let requestPumpErrorReported = false;
@@ -15149,6 +15176,8 @@ function managedAgentEnvironmentError() {
   if (!validId(e.PI_HERDSMAN_RUN_ID)) return "PI_HERDSMAN_RUN_ID invalid";
   if (!validId(e.PI_HERDSMAN_OWNER_SESSION_ID))
     return "PI_HERDSMAN_OWNER_SESSION_ID invalid";
+  if (!e.PI_HERDSMAN_OWNER_DISPLAY?.trim())
+    return "PI_HERDSMAN_OWNER_DISPLAY missing";
   if (!e.PI_HERDSMAN_LABEL || !AGENT_LABEL_PATTERN2.test(e.PI_HERDSMAN_LABEL))
     return "PI_HERDSMAN_LABEL invalid";
   if (!e.PI_HERDSMAN_WORKSPACE_ID?.trim())
@@ -15170,7 +15199,13 @@ function sessionContextRetired(entries, sessionId) {
     (entry) => entry?.type === "custom" && entry.customType === AGENT_CONTEXT_RETIRED_ENTRY && entry.data?.sessionId === sessionId
   );
 }
+function sessionRetirementGuidanceVisible(ctx, sessionId) {
+  return buildSessionProjection2(ctx.sessionManager.getBranch()).entries.some(
+    ({ sourceEntry, messages }) => sourceEntry.type === "custom_message" && sourceEntry.customType === AGENT_CONTEXT_RETIRED_ENTRY && sourceEntry.details?.sessionId === sessionId && messages.length > 0
+  );
+}
 function registerManagedAgentContextHandlers(pi, options) {
+  let overflowRetryGuidance;
   pi.on(
     "session_before_compact",
     (event, ctx) => {
@@ -15179,24 +15214,46 @@ function registerManagedAgentContextHandlers(pi, options) {
       if (event.reason === "manual") return;
       const sessionId = ctx.sessionManager.getSessionId();
       const entries = ctx.sessionManager.getEntries();
-      if (!sessionContextRetired(entries, sessionId))
-        pi.appendEntry(AGENT_CONTEXT_RETIRED_ENTRY, { sessionId });
+      const retired = sessionContextRetired(entries, sessionId);
+      const guided = sessionRetirementGuidanceVisible(ctx, sessionId);
+      let guidance;
+      if (!retired) pi.appendEntry(AGENT_CONTEXT_RETIRED_ENTRY, { sessionId });
+      if (!guided) guidance = CONTEXT_RETIREMENT_INSTRUCTION;
+      else if (event.reason === "overflow")
+        guidance = CONTEXT_RETIREMENT_REMINDER;
+      if (guidance) {
+        pi.sendMessage(
+          {
+            customType: AGENT_CONTEXT_RETIRED_ENTRY,
+            content: guidance,
+            display: false,
+            details: { sessionId }
+          },
+          { triggerTurn: false }
+        );
+        if (event.reason === "overflow" && event.willRetry)
+          overflowRetryGuidance = guidance;
+      }
       if (event.reason === "threshold") return { cancel: true };
     }
   );
-  pi.on("context", (event, ctx) => {
-    if (!options.contextRetirementEnabled()) return;
-    if (!options.hasActiveAssignment()) return;
-    const sessionId = ctx.sessionManager.getSessionId();
-    if (!sessionContextRetired(ctx.sessionManager.getEntries(), sessionId))
-      return;
+  pi.on("session_compact_failed", (event) => {
+    if (event.reason === "overflow") overflowRetryGuidance = void 0;
+  });
+  pi.on("agent_settled", () => {
+    overflowRetryGuidance = void 0;
+  });
+  pi.on("context", (event) => {
+    if (!overflowRetryGuidance) return;
+    const content = overflowRetryGuidance;
+    overflowRetryGuidance = void 0;
     return {
       messages: [
         ...event.messages,
         {
           role: "custom",
           customType: AGENT_CONTEXT_RETIRED_ENTRY,
-          content: CONTEXT_RETIREMENT_INSTRUCTION,
+          content,
           display: false,
           timestamp: Date.now()
         }
@@ -18660,7 +18717,7 @@ function createLeadCoordinationRuntime(host) {
     listPeerLeadRecords: listPeerLeadRecords2,
     publishProjectMessage,
     resolveMessageFiles: resolveMessageFiles2,
-    buildSessionProjection: buildSessionProjection3,
+    buildSessionProjection: buildSessionProjection4,
     contentText: contentText6,
     supervisorStateType,
     workspacePresentationProvenance: workspacePresentationProvenance2,
@@ -19054,7 +19111,7 @@ function createLeadCoordinationRuntime(host) {
   };
   const latestCustomMessageText = (ctx, customType) => {
     const entry = [
-      ...buildSessionProjection3(ctx.sessionManager.getBranch()).entries
+      ...buildSessionProjection4(ctx.sessionManager.getBranch()).entries
     ].reverse().find(
       (candidate) => candidate.sourceEntry.type === "custom_message" && candidate.sourceEntry.customType === customType && candidate.messages.length > 0
     );
@@ -21017,9 +21074,6 @@ var LEAD_ROLE_CHARTER = `## Lead role
 ${LEAD_SCOPE_DESCRIPTION}
 ${LEAD_SUPERVISOR_PEER_GUIDANCE}
 ${FILE_HANDOFF_GUIDANCE}`;
-var DELEGATING_AGENT_ROLE_CHARTER = `## Delegating agent role
-${DELEGATING_AGENT_SCOPE_DESCRIPTION}
-${FILE_HANDOFF_GUIDANCE}`;
 var MANAGER_ROLE_CHARTER = `## Manager role
 Manage project work by branch. Use staff_delegate with a task and optional branch
 to start new project work. Use staff_resume with its branch to resume existing
@@ -21614,125 +21668,6 @@ ${globalInstructions}
   const currentChief = (failOnVerificationError = false) => roleTransitions.currentChief(failOnVerificationError);
   const managerForScope = (scope) => roleTransitions.managerForScope(scope);
   const currentWorktreeScope = (ctx) => roleTransitions.currentWorktreeScope(ctx);
-  const managedSupervisorWorktreeScope = async (ctx) => {
-    const workspaceId = process.env.HERDR_WORKSPACE_ID;
-    if (!workspaceId) return void 0;
-    try {
-      return await worktreeGroupScope(pi, ctx, workspaceId, ctx.signal);
-    } catch (error2) {
-      if (error2 instanceof OperationError && error2.detail.details?.herdrCode === "not_git_worktree")
-        return void 0;
-      throw error2;
-    }
-  };
-  const managedSupervisorAgent = (ctx, descriptor) => verifiedHerdrAgent(descriptor, {
-    listAgents: async () => (await listAllHerdrAgents(pi, ctx, ctx.signal)).agents,
-    getAgent: async (paneId) => (await runHerdr(pi, ctx, ["agent", "get", paneId], {
-      signal: ctx.signal
-    }))?.agent,
-    expectedSession: expectedSession2,
-    isPiAgent,
-    matchesExpectedSession
-  });
-  const managedCurrentManager = async (ctx, scope) => {
-    const currentScope = scope === null || scope === void 0 ? await managedSupervisorWorktreeScope(ctx) : scope;
-    if (!currentScope) return void 0;
-    const status = readManagerDescriptorStatus(
-      supervisionRuntime(),
-      currentScope.primaryWorkspaceId
-    );
-    if (!status || !status.live) return void 0;
-    if (status.descriptor.repoKey !== currentScope.repoKey)
-      throw new Error("Manager authority does not match project");
-    verifyManagerCoordinationAuthority(
-      status.descriptor,
-      readLeadCoordinationState(
-        supervisionRuntime(),
-        status.descriptor.piSessionId
-      ),
-      HERDSMAN_BUILD,
-      requireCompatibleBuild
-    );
-    if (!await managedSupervisorAgent(ctx, status.descriptor))
-      throw new Error(
-        "Manager authority exists but live discovery is inconclusive"
-      );
-    return status.descriptor;
-  };
-  const managedCurrentChief = async (ctx, failOnVerificationError = false) => {
-    const runtime = supervisionRuntime();
-    const leaseMayExist = () => {
-      try {
-        statSync7(runtime.lock);
-        return true;
-      } catch (error2) {
-        if (error2.code === "ENOENT") return false;
-        throw error2;
-      }
-    };
-    let descriptor;
-    try {
-      descriptor = readChiefDescriptor(runtime.descriptor);
-    } catch (error2) {
-      if (failOnVerificationError && leaseMayExist()) throw error2;
-      return void 0;
-    }
-    requireCompatibleBuild(
-      HERDSMAN_BUILD,
-      descriptor.build,
-      "supervision",
-      `Chief ${descriptor.piSessionId}`
-    );
-    if (!chiefLeaseIsHeld(runtime)) {
-      if (failOnVerificationError && leaseMayExist())
-        throw new Error("Unable to verify Chief supervision lease");
-      return void 0;
-    }
-    try {
-      const verified = await verifyRemoteChiefAuthority(descriptor, {
-        remoteIdentity: () => managedSupervisorAgent(ctx, descriptor),
-        requireCompatibleBuild,
-        build: HERDSMAN_BUILD
-      });
-      if (!verified) return void 0;
-      return descriptor;
-    } catch (error2) {
-      if (error2 instanceof OperationError && error2.detail.category === "incompatible_build")
-        throw error2;
-      if (failOnVerificationError) throw error2;
-      return void 0;
-    }
-  };
-  const prepareManagedSupervisorState = async (ctx) => {
-    const content = await leadSupervisorState(ctx, {
-      currentWorktreeScope: managedSupervisorWorktreeScope,
-      projectAssignmentForScope: (scope, sessionId) => {
-        const assignments = findProjectAssignmentBySession(
-          supervisionRuntime(),
-          scope.repoKey,
-          sessionId
-        );
-        if (assignments.length > 1)
-          throw new Error(
-            "Multiple project assignments match the Lead session"
-          );
-        return assignments[0];
-      },
-      currentManager: managedCurrentManager,
-      currentChiefAuthority: managedCurrentChief
-    });
-    const latest = [
-      ...buildSessionProjection2(ctx.sessionManager.getBranch()).entries
-    ].reverse().find(
-      (candidate) => candidate.sourceEntry.type === "custom_message" && candidate.sourceEntry.customType === SUPERVISOR_STATE_TYPE && candidate.messages.length > 0
-    );
-    const latestMessage = latest?.messages[0];
-    return supervisorStateMessage(
-      SUPERVISOR_STATE_TYPE,
-      content,
-      latestMessage ? contentText5(latestMessage.content, "") : void 0
-    );
-  };
   const currentManager = (ctx, scope = null) => roleTransitions.currentManager(ctx, scope);
   const currentSupervisor = (ctx) => roleTransitions.currentSupervisor(ctx);
   const liveAgent = (...args) => leadRuntimes.liveAgent(...args);
@@ -22416,7 +22351,7 @@ ${summary}`,
           messageLimits: messageLimits2,
           chiefMessageBytes,
           coordinationMessageMaxBytes: COORDINATION_MESSAGE_MAX_BYTES,
-          buildSessionProjection: buildSessionProjection2,
+          buildSessionProjection: buildSessionProjection3,
           contentText: contentText5,
           supervisorStateType: SUPERVISOR_STATE_TYPE,
           sameManagerDescriptor,
@@ -22546,10 +22481,6 @@ ${summary}`,
     resolveMessageFiles,
     currentTurnMessage,
     getAgentDefinitions: async (ctx) => (await contextAgentDefinitions(ctx)).definitions,
-    prepareDelegatingStart: async (ctx) => ({
-      roleCharter: DELEGATING_AGENT_ROLE_CHARTER,
-      supervisorStateMessage: await prepareManagedSupervisorState(ctx)
-    }),
     appendError: (ctx, kind, error2) => appendDurableError(pi, ctx, kind, error2)
   });
 }