@melihmucuk/pi-crew 1.0.1 → 1.0.2

package/README.md

@@ -68,12 +68,12 @@ Closes an interactive subagent session owned by the current session when you no
 "close planner-a1b2, the plan looks good"
 ```
 
-### `/pi-crew:abort`
+### `/pi-crew-abort`
 
 Aborts a running subagent. Supports tab completion for subagent IDs.
 Unlike the `crew_abort` tool, this command is intentionally unrestricted and works as an emergency escape hatch across sessions.
 
-### `/pi-crew:review`
+### `/pi-crew-review`
 
 Expands a bundled prompt template that orchestrates parallel code and quality reviews.
 Use it to review recent commits, staged changes, unstaged changes, and untracked files with `code-reviewer` and `quality-reviewer`, then merge both results into one report.

package/dist/crew-manager.d.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { AgentConfig } from "./agent-discovery.js";
 import { type AbortableAgentSummary, type ActiveAgentSummary } from "./runtime/subagent-state.js";
-export type { AbortableAgentSummary, ActiveAgentSummary } from "./runtime/subagent-state.js";
+export type { AbortableAgentSummary, ActiveAgentSummary, } from "./runtime/subagent-state.js";
 export interface AbortOwnedResult {
     abortedIds: string[];
     missingIds: string[];
@@ -14,6 +14,7 @@ export declare class CrewManager {
     private extensionResolvedPath;
     private registry;
     private delivery;
+    private overflowAbortControllers;
     onWidgetUpdate: (() => void) | undefined;
     constructor(extensionResolvedPath: string);
     activateSession(sessionId: string, isIdle: () => boolean, pi: ExtensionAPI): void;

package/dist/crew-manager.js

@@ -1,5 +1,6 @@
 import { bootstrapSession } from "./bootstrap-session.js";
 import { DeliveryCoordinator } from "./runtime/delivery-coordinator.js";
+import { runPromptWithOverflowRecovery } from "./runtime/overflow-recovery.js";
 import { SubagentRegistry } from "./runtime/subagent-registry.js";
 import { isAbortableStatus, isAborted, } from "./runtime/subagent-state.js";
 function getLastAssistantMessage(messages) {
@@ -46,6 +47,7 @@ export class CrewManager {
     extensionResolvedPath;
     registry = new SubagentRegistry();
     delivery = new DeliveryCoordinator();
+    overflowAbortControllers = new Map();
     onWidgetUpdate;
     constructor(extensionResolvedPath) {
         this.extensionResolvedPath = extensionResolvedPath;
@@ -111,11 +113,21 @@ export class CrewManager {
     async runPromptCycle(state, prompt, pi) {
         if (isAborted(state))
             return;
+        const abortController = new AbortController();
+        this.overflowAbortControllers.set(state.id, abortController);
         try {
-            await state.session.prompt(prompt);
+            const recovery = await runPromptWithOverflowRecovery(state.session, prompt, abortController.signal);
             if (isAborted(state))
                 return;
             const outcome = getPromptOutcome(state);
+            // If overflow recovery ran but failed, keep the error from outcome.
+            // If it recovered, outcome now reflects the retry turn's result.
+            if (recovery === "failed" && outcome.status !== "error") {
+                this.settleAgent(state, "error", {
+                    error: "Context overflow recovery failed",
+                }, pi);
+                return;
+            }
             this.settleAgent(state, outcome.status, outcome, pi);
         }
         catch (err) {
@@ -124,6 +136,9 @@ export class CrewManager {
             const error = err instanceof Error ? err.message : String(err);
             this.settleAgent(state, "error", { error }, pi);
         }
+        finally {
+            this.overflowAbortControllers.delete(state.id);
+        }
     }
     async spawnSession(state, cwd, parentSessionFile, ctx, pi) {
         try {
@@ -159,7 +174,9 @@ export class CrewManager {
             return { error: `Subagent "${id}" belongs to a different session` };
         }
         if (state.status !== "waiting") {
-            return { error: `Subagent "${id}" is not waiting for a response (status: ${state.status})` };
+            return {
+                error: `Subagent "${id}" is not waiting for a response (status: ${state.status})`,
+            };
         }
         if (!state.session)
             return { error: `Subagent "${id}" has no active session` };
@@ -185,6 +202,10 @@ export class CrewManager {
         const state = this.registry.get(id);
         if (!state || !isAbortableStatus(state.status))
             return false;
+        this.overflowAbortControllers.get(id)?.abort();
+        this.overflowAbortControllers.delete(id);
+        state.session?.abortCompaction();
+        state.session?.abortRetry();
         state.session?.abort().catch(() => { });
         this.settleAgent(state, "aborted", { error: opts.reason }, pi);
         return true;
@@ -223,7 +244,9 @@ export class CrewManager {
         return ids;
     }
     abortForOwner(ownerSessionId, pi) {
-        this.abortAllOwned(ownerSessionId, pi, { reason: "Aborted on session shutdown" });
+        this.abortAllOwned(ownerSessionId, pi, {
+            reason: "Aborted on session shutdown",
+        });
         this.delivery.clearPendingForOwner(ownerSessionId);
     }
     getAbortableAgents() {

package/dist/integration/register-command.js

@@ -1,5 +1,5 @@
 export function registerCrewCommand(pi, crewManager) {
-    pi.registerCommand("pi-crew:abort", {
+    pi.registerCommand("pi-crew-abort", {
         description: "Abort an active subagent",
         getArgumentCompletions(argumentPrefix) {
             const activeAgents = crewManager.getAbortableAgents();

package/dist/integration/tools/crew-spawn.js

@@ -5,7 +5,7 @@ export function registerCrewSpawnTool({ pi, crewManager, notifyDiscoveryWarnings
     pi.registerTool({
         name: "crew_spawn",
         label: "Spawn Crew",
-        description: "Spawn a non-blocking subagent that runs in an isolated session. The subagent works independently while the current session stays interactive. Results are delivered back to the spawning session as steering messages when done. Use crew_list first to see available subagents.",
+        description: "Spawn a non-blocking subagent that runs in an isolated session. The subagent works independently while your session stays interactive. Results are delivered back to your session as steering messages when done. NEVER PREDICT or FABRICATE results for subagents that have not yet reported back to you. Use crew_list first to see available subagents.",
         parameters: Type.Object({
             subagent: Type.String({ description: "Subagent name from crew_list" }),
             task: Type.String({ description: "Task to delegate to the subagent" }),
@@ -14,10 +14,10 @@ export function registerCrewSpawnTool({ pi, crewManager, notifyDiscoveryWarnings
         promptGuidelines: [
             "Use crew_* tools to delegate parallelizable, independent tasks to specialized subagents. For interactive multi-turn workflows, use crew_respond/crew_done. Avoid spawning for trivial, single-turn tasks.",
             "crew_spawn: Always call crew_list first to see which subagents are available before spawning.",
-            "crew_spawn: The spawned subagent runs in a separate context window with no access to the current conversation. Include all relevant context (file paths, requirements, prior findings) directly in the task parameter.",
+            "crew_spawn: The spawned subagent runs in a separate context window with no access to your session. Include all relevant context (file paths, requirements, prior findings) directly in the task parameter.",
             "crew_spawn: Results are delivered asynchronously as steering messages. Do not block or poll for completion. If there are other independent tasks to handle, continue with those; otherwise wait for the user's next instruction or the subagent result.",
             "crew_spawn: NEVER perform the same work you delegated to a subagent. Once a task is spawned, trust the subagent to do it. Do not run the same searches, reads, or analysis yourself while waiting. You may only gather context BEFORE spawning to prepare the task description. After spawning, move on to other independent work or simply wait for the result.",
-            "crew_spawn: When multiple subagents are spawned, each result arrives as a separate steering message. NEVER predict or fabricate results for subagents that have not yet reported back. Wait for ALL crew-result messages.",
+            "crew_spawn: When multiple subagents are spawned, each result arrives as a separate steering message. NEVER PREDICT or FABRICATE results for subagents that have not yet reported back to you. Wait for ALL crew-result messages.",
             "crew_spawn: Interactive subagents (marked with 'interactive' in crew_list) stay alive after responding. Use crew_respond to continue the conversation and crew_done to close when finished.",
         ],
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/dist/runtime/overflow-recovery.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+export type OverflowRecoveryResult = "none" | "recovered" | "failed";
+export declare function runPromptWithOverflowRecovery(session: AgentSession, text: string, signal: AbortSignal): Promise<OverflowRecoveryResult>;

package/dist/runtime/overflow-recovery.js

@@ -0,0 +1,155 @@
+const OVERFLOW_RECOVERY_TIMEOUT_MS = 120_000;
+/**
+ * Short grace period for the first terminal agent_end after prompt() resolves.
+ * If this window expires, we still wait the full recovery timeout.
+ */
+const INITIAL_AGENT_END_WAIT_MS = 5_000;
+function createDeferredPhase() {
+    let done = false;
+    let resolveFn;
+    const promise = new Promise((resolve) => {
+        resolveFn = () => {
+            if (done)
+                return;
+            done = true;
+            resolve();
+        };
+    });
+    return {
+        promise,
+        resolve: () => resolveFn?.(),
+        isDone: () => done,
+    };
+}
+class OverflowRecoveryTracker {
+    overflowDetected = false;
+    compactionWillRetry = false;
+    autoRetryActive = false;
+    initialAgentEnd = createDeferredPhase();
+    compactionEnd;
+    retryAgentEnd;
+    overflowAutoRetryEnd;
+    timers = [];
+    handleEvent(event) {
+        switch (event.type) {
+            case "agent_end":
+                this.onAgentEnd();
+                break;
+            case "compaction_start":
+                this.onCompactionStart(event.reason);
+                break;
+            case "compaction_end":
+                this.onCompactionEnd(event.reason, event.willRetry);
+                break;
+            case "auto_retry_start":
+                this.onAutoRetryStart();
+                break;
+            case "auto_retry_end":
+                this.onAutoRetryEnd();
+                break;
+            default:
+                break;
+        }
+    }
+    async awaitCompletion(signal) {
+        const cancelPromise = new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve();
+                return;
+            }
+            signal.addEventListener("abort", () => resolve(), { once: true });
+        });
+        try {
+            let initialEnd = await this.waitForPhase(this.initialAgentEnd.promise, INITIAL_AGENT_END_WAIT_MS, cancelPromise);
+            if (initialEnd === "timeout") {
+                initialEnd = await this.waitForPhase(this.initialAgentEnd.promise, OVERFLOW_RECOVERY_TIMEOUT_MS, cancelPromise);
+            }
+            if (initialEnd !== "done") {
+                return this.overflowDetected ? "failed" : "none";
+            }
+            if (!this.overflowDetected)
+                return "none";
+            if (this.compactionEnd) {
+                const compactionEnd = await this.waitForPhase(this.compactionEnd.promise, OVERFLOW_RECOVERY_TIMEOUT_MS, cancelPromise);
+                if (compactionEnd !== "done")
+                    return "failed";
+            }
+            if (!this.compactionWillRetry)
+                return "failed";
+            if (this.retryAgentEnd) {
+                const retryEnd = await this.waitForPhase(this.retryAgentEnd.promise, OVERFLOW_RECOVERY_TIMEOUT_MS, cancelPromise);
+                if (retryEnd !== "done")
+                    return "failed";
+            }
+            if (this.overflowAutoRetryEnd) {
+                const autoRetryEnd = await this.waitForPhase(this.overflowAutoRetryEnd.promise, OVERFLOW_RECOVERY_TIMEOUT_MS, cancelPromise);
+                if (autoRetryEnd !== "done")
+                    return "failed";
+            }
+            return "recovered";
+        }
+        finally {
+            for (const timer of this.timers)
+                clearTimeout(timer);
+        }
+    }
+    async waitForPhase(phasePromise, timeoutMs, cancelPromise) {
+        return Promise.race([
+            phasePromise.then(() => "done"),
+            cancelPromise.then(() => "cancelled"),
+            new Promise((resolve) => {
+                this.timers.push(setTimeout(() => resolve("timeout"), timeoutMs));
+            }),
+        ]);
+    }
+    // agent_end can be followed immediately by auto_retry_start in the same
+    // _processAgentEvent tick. Resolve on microtask so we can ignore retrying
+    // attempts and only accept terminal agent_end events.
+    onAgentEnd() {
+        queueMicrotask(() => {
+            if (this.autoRetryActive)
+                return;
+            if (!this.initialAgentEnd.isDone()) {
+                this.initialAgentEnd.resolve();
+                return;
+            }
+            this.retryAgentEnd?.resolve();
+        });
+    }
+    onCompactionStart(reason) {
+        if (reason !== "overflow")
+            return;
+        this.overflowDetected = true;
+        this.compactionEnd ??= createDeferredPhase();
+    }
+    onCompactionEnd(reason, willRetry) {
+        if (reason !== "overflow")
+            return;
+        this.compactionWillRetry = willRetry;
+        if (willRetry) {
+            this.retryAgentEnd ??= createDeferredPhase();
+        }
+        this.compactionEnd?.resolve();
+    }
+    onAutoRetryStart() {
+        this.autoRetryActive = true;
+        if (this.overflowDetected) {
+            this.overflowAutoRetryEnd ??= createDeferredPhase();
+        }
+    }
+    onAutoRetryEnd() {
+        this.autoRetryActive = false;
+        this.overflowAutoRetryEnd?.resolve();
+    }
+}
+export async function runPromptWithOverflowRecovery(session, text, signal) {
+    const tracker = new OverflowRecoveryTracker();
+    const unsubscribe = session.subscribe((event) => tracker.handleEvent(event));
+    try {
+        await session.prompt(text);
+        return await tracker.awaitCompletion(signal);
+    }
+    finally {
+        unsubscribe();
+    }
+}

package/docs/architecture.md

@@ -199,7 +199,7 @@ File:
 
 - `extension/integration/register-command.ts`
 
-The extension also registers the `/pi-crew:abort` command.
+The extension also registers the `/pi-crew-abort` command.
 
 This command differs from `crew_abort` in one important way:
 
@@ -616,7 +616,7 @@ That last point is essential. The latest subagent response was already delivered
 There are three conceptually different abort sources:
 
 1. tool-triggered aborts through `crew_abort`
-2. unrestricted manual aborts through `/pi-crew:abort`
+2. unrestricted manual aborts through `/pi-crew-abort`
 3. cleanup aborts when an owner session shuts down
 
 Each path should report the real reason.
@@ -648,7 +648,7 @@ Relevant file:
 
 - `extension/integration/register-command.ts`
 
-`/pi-crew:abort` can target any active abortable subagent, regardless of owner. This is not a bug. It is an explicit operational decision.
+`/pi-crew-abort` can target any active abortable subagent, regardless of owner. This is not a bug. It is an explicit operational decision.
 
 ### 11.4 Session shutdown cleanup
 
@@ -691,7 +691,7 @@ This prevents cross-session interference in normal tool-driven workflows.
 
 ### 12.3 What is intentionally not isolated
 
-The emergency command `/pi-crew:abort` is intentionally cross-session.
+The emergency command `/pi-crew-abort` is intentionally cross-session.
 
 This is the only major exception to normal ownership isolation.
 
@@ -752,7 +752,7 @@ Architecturally, these files are not special-cased by the runtime. They are auto
 
 File:
 
-- `prompts/pi-crew:review.md`
+- `prompts/pi-crew-review.md`
 
 This prompt template is a good example of how `pi-crew` is meant to be consumed by higher-level orchestration prompts.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melihmucuk/pi-crew",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "Non-blocking subagent orchestration for pi coding agent",
   "files": [
@@ -49,4 +49,4 @@
     "@types/node": "^22.19.3",
     "typescript": "^5.9.3"
   }
-}
+}