@ladbabynpm/picc-subagents 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ladbabynpm/picc-subagents",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"description": "Claude Code style Agent tool for pi agent. Fork of tintinweb/pi-subagents, better aligned with the harness of Claude Code.",
 	"author": "ladbabynpm",
 	"license": "MIT",

package/src/group-join.ts

@@ -1,141 +1,173 @@
-/**
- * group-join.ts — Manages grouped background agent completion notifications.
- *
- * Instead of each agent individually nudging the main agent on completion,
- * agents in a group are held until all complete (or a timeout fires),
- * then a single consolidated notification is sent.
- */
-
-import type { AgentRecord } from "./types.js";
-
-export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
-
-interface AgentGroup {
-  groupId: string;
-  agentIds: Set<string>;
-  completedRecords: Map<string, AgentRecord>;
-  timeoutHandle?: ReturnType<typeof setTimeout>;
-  delivered: boolean;
-  /** Shorter timeout for stragglers after a partial delivery. */
-  isStraggler: boolean;
-}
-
-/** Default timeout: 30s after first completion in a group. */
-const DEFAULT_TIMEOUT = 30_000;
-/** Straggler re-batch timeout: 15s. */
-const STRAGGLER_TIMEOUT = 15_000;
-
-export class GroupJoinManager {
-  private groups = new Map<string, AgentGroup>();
-  private agentToGroup = new Map<string, string>();
-
-  constructor(
-    private deliverCb: DeliveryCallback,
-    private groupTimeout = DEFAULT_TIMEOUT,
-  ) {}
-
-  /** Register a group of agent IDs that should be joined. */
-  registerGroup(groupId: string, agentIds: string[]): void {
-    const group: AgentGroup = {
-      groupId,
-      agentIds: new Set(agentIds),
-      completedRecords: new Map(),
-      delivered: false,
-      isStraggler: false,
-    };
-    this.groups.set(groupId, group);
-    for (const id of agentIds) {
-      this.agentToGroup.set(id, groupId);
-    }
-  }
-
-  /**
-   * Called when an agent completes.
-   * Returns:
-   * - 'pass'      — agent is not grouped, caller should send individual nudge
-   * - 'held'      — result held, waiting for group completion
-   * - 'delivered'  — this completion triggered the group notification
-   */
-  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
-    const groupId = this.agentToGroup.get(record.id);
-    if (!groupId) return 'pass';
-
-    const group = this.groups.get(groupId);
-    if (!group || group.delivered) return 'pass';
-
-    group.completedRecords.set(record.id, record);
-
-    // All done — deliver immediately
-    if (group.completedRecords.size >= group.agentIds.size) {
-      this.deliver(group, false);
-      return 'delivered';
-    }
-
-    // First completion in this batch — start timeout
-    if (!group.timeoutHandle) {
-      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
-      group.timeoutHandle = setTimeout(() => {
-        this.onTimeout(group);
-      }, timeout);
-    }
-
-    return 'held';
-  }
-
-  private onTimeout(group: AgentGroup): void {
-    if (group.delivered) return;
-    group.timeoutHandle = undefined;
-
-    // Partial delivery — some agents still running
-    const remaining = new Set<string>();
-    for (const id of group.agentIds) {
-      if (!group.completedRecords.has(id)) remaining.add(id);
-    }
-
-    // Clean up agentToGroup for delivered agents (they won't complete again)
-    for (const id of group.completedRecords.keys()) {
-      this.agentToGroup.delete(id);
-    }
-
-    // Deliver what we have
-    this.deliverCb([...group.completedRecords.values()], true);
-
-    // Set up straggler group for remaining agents
-    group.completedRecords.clear();
-    group.agentIds = remaining;
-    group.isStraggler = true;
-    // Timeout will be started when the next straggler completes
-  }
-
-  private deliver(group: AgentGroup, partial: boolean): void {
-    if (group.timeoutHandle) {
-      clearTimeout(group.timeoutHandle);
-      group.timeoutHandle = undefined;
-    }
-    group.delivered = true;
-    this.deliverCb([...group.completedRecords.values()], partial);
-    this.cleanupGroup(group.groupId);
-  }
-
-  private cleanupGroup(groupId: string): void {
-    const group = this.groups.get(groupId);
-    if (!group) return;
-    for (const id of group.agentIds) {
-      this.agentToGroup.delete(id);
-    }
-    this.groups.delete(groupId);
-  }
-
-  /** Check if an agent is in a group. */
-  isGrouped(agentId: string): boolean {
-    return this.agentToGroup.has(agentId);
-  }
-
-  dispose(): void {
-    for (const group of this.groups.values()) {
-      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
-    }
-    this.groups.clear();
-    this.agentToGroup.clear();
-  }
-}
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ *
+ * The hold is bounded by the main agent's own turn: `flush()` is called when
+ * that turn settles, because from that point on a held result is only latency —
+ * see the method for the full reasoning.
+ */
+
+import type { AgentRecord } from "./types.js";
+
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+  groupId: string;
+  agentIds: Set<string>;
+  completedRecords: Map<string, AgentRecord>;
+  timeoutHandle?: ReturnType<typeof setTimeout>;
+  delivered: boolean;
+  /** Shorter timeout for stragglers after a partial delivery. */
+  isStraggler: boolean;
+}
+
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+  private groups = new Map<string, AgentGroup>();
+  private agentToGroup = new Map<string, string>();
+
+  constructor(
+    private deliverCb: DeliveryCallback,
+    private groupTimeout = DEFAULT_TIMEOUT,
+  ) {}
+
+  /** Register a group of agent IDs that should be joined. */
+  registerGroup(groupId: string, agentIds: string[]): void {
+    const group: AgentGroup = {
+      groupId,
+      agentIds: new Set(agentIds),
+      completedRecords: new Map(),
+      delivered: false,
+      isStraggler: false,
+    };
+    this.groups.set(groupId, group);
+    for (const id of agentIds) {
+      this.agentToGroup.set(id, groupId);
+    }
+  }
+
+  /**
+   * Called when an agent completes.
+   * Returns:
+   * - 'pass'      — agent is not grouped, caller should send individual nudge
+   * - 'held'      — result held, waiting for group completion
+   * - 'delivered'  — this completion triggered the group notification
+   */
+  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
+    const groupId = this.agentToGroup.get(record.id);
+    if (!groupId) return 'pass';
+
+    const group = this.groups.get(groupId);
+    if (!group || group.delivered) return 'pass';
+
+    group.completedRecords.set(record.id, record);
+
+    // All done — deliver immediately
+    if (group.completedRecords.size >= group.agentIds.size) {
+      this.deliver(group, false);
+      return 'delivered';
+    }
+
+    // First completion in this batch — start timeout
+    if (!group.timeoutHandle) {
+      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+      group.timeoutHandle = setTimeout(() => {
+        this.onTimeout(group);
+      }, timeout);
+    }
+
+    return 'held';
+  }
+
+  private onTimeout(group: AgentGroup): void {
+    if (group.delivered) return;
+    group.timeoutHandle = undefined;
+
+    // Partial delivery — some agents still running
+    const remaining = new Set<string>();
+    for (const id of group.agentIds) {
+      if (!group.completedRecords.has(id)) remaining.add(id);
+    }
+
+    // Clean up agentToGroup for delivered agents (they won't complete again)
+    for (const id of group.completedRecords.keys()) {
+      this.agentToGroup.delete(id);
+    }
+
+    // Deliver what we have
+    this.deliverCb([...group.completedRecords.values()], true);
+
+    // Set up straggler group for remaining agents
+    group.completedRecords.clear();
+    group.agentIds = remaining;
+    group.isStraggler = true;
+    // Timeout will be started when the next straggler completes
+  }
+
+  private deliver(group: AgentGroup, partial: boolean): void {
+    if (group.timeoutHandle) {
+      clearTimeout(group.timeoutHandle);
+      group.timeoutHandle = undefined;
+    }
+    group.delivered = true;
+    this.deliverCb([...group.completedRecords.values()], partial);
+    this.cleanupGroup(group.groupId);
+  }
+
+  private cleanupGroup(groupId: string): void {
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    for (const id of group.agentIds) {
+      this.agentToGroup.delete(id);
+    }
+    this.groups.delete(groupId);
+  }
+
+  /**
+   * Deliver every held record immediately and release the remaining members so
+   * each notifies on its own.
+   *
+   * Called when the main agent's turn settles. At that point a held result is
+   * pure added latency: nothing consumes it until a new turn starts, so waiting
+   * for siblings or for the join timeout buys nothing. This mirrors Claude Code,
+   * which drains whichever task notifications are already queued when the turn
+   * ends and never blocks on unfinished siblings.
+   *
+   * Records are delivered as partial, because by definition siblings were still
+   * running when the turn ended. `deliver()` clears the timer and drops every
+   * agentToGroup entry for the group, so still-running members become ungrouped
+   * and report individually — the hold is deliberately not re-armed for them.
+   *
+   * @returns the number of records delivered.
+   */
+  flush(): number {
+    // deliver() deletes from this.groups, so iterate over a snapshot.
+    let delivered = 0;
+    for (const group of [...this.groups.values()]) {
+      if (group.delivered || group.completedRecords.size === 0) continue;
+      delivered += group.completedRecords.size;
+      this.deliver(group, true);
+    }
+    return delivered;
+  }
+
+  /** Check if an agent is in a group. */
+  isGrouped(agentId: string): boolean {
+    return this.agentToGroup.has(agentId);
+  }
+
+  dispose(): void {
+    for (const group of this.groups.values()) {
+      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+    }
+    this.groups.clear();
+    this.agentToGroup.clear();
+  }
+}

package/src/index.ts

@@ -313,19 +313,21 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
-  // Deliver a completion report so the main agent is told about it without
-  // being held up. pi's sendMessage routes by the agent's *current* streaming
-  // state at call time, not by the options we pass: when we're mid-run it
-  // queues a followUp and *silently ignores* `triggerTurn`; once the run ends
-  // nothing re-checks the queue, so a report sent during the run only surfaces
-  // on the next user prompt. So pick the delivery mode by liveness:
-  //   - busy  -> queue a plain followUp (drains when the run finishes)
-  //   - idle  -> deliver now with a real turn, so the report arrives at once
+  // Deliver a completion report so the main agent learns about it without being
+  // interrupted mid-work. `triggerTurn` must ALWAYS be set: pi routes by the
+  // session's live state at call time, and without it an idle session takes the
+  // final branch of `sendCustomMessage` — appended to the session with no turn
+  // and never queued — so the report would wait for the next user prompt.
+  // With it, both states work without inspecting liveness ourselves:
+  //   - streaming -> queued as followUp, drained when the run's tool loop ends
+  //     (equivalent to Claude Code's `later` priority: end-of-turn, no interrupt)
+  //   - idle      -> starts a turn immediately, so the report arrives at once
+  // Deriving this from `ctx.isIdle()` is a trap: `currentCtx` is captured at
+  // tool_execution_start, so it can report "busy" after the run already ended.
   function deliverReport(content: string, details: NotificationDetails) {
-    const busy = currentCtx ? !currentCtx.isIdle() : false;
     pi.sendMessage<NotificationDetails>(
       { customType: "subagent-notification", content, display: true, details },
-      busy ? { deliverAs: "followUp" } : { deliverAs: "followUp", triggerTurn: true },
+      { deliverAs: "followUp", triggerTurn: true },
     );
   }
 
@@ -376,6 +378,25 @@ export default function (pi: ExtensionAPI) {
     30_000,
   );
 
+  // Flush held group results the moment the main agent's turn settles.
+  //
+  // Without this, a finished agent in a smart/group batch waits for its siblings
+  // or for the 30s join timeout even though the main agent has gone idle and
+  // nothing can consume the result until a new turn starts — the hold is pure
+  // added latency. Claude Code behaves the same way: it drains whichever task
+  // notifications are already queued when the turn ends, and never blocks on
+  // unfinished siblings.
+  //
+  // `agent_settled` (not `agent_end`) is the correct boundary: agent_end can
+  // still be followed by an automatic retry, auto-compaction, or a queued
+  // follow-up continuation, during which the main agent is still working and the
+  // group hold is still doing its job. Flushing here cannot loop — our own
+  // notification triggers a further run, and that run's settle finds nothing left
+  // to flush.
+  pi.on("agent_settled", async () => {
+    groupJoin.flush();
+  });
+
   /** Helper: build event data for lifecycle events from an AgentRecord. */
   function buildEventData(record: AgentRecord) {
     const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;