@tranhoangnguyen0310/pi-flow-external 1.2.0-external.0 → 1.3.0-external.0

package/AGENTS.md

@@ -29,7 +29,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 - A backend failure with a complete local record is different from an incomplete or damaged record; preserve that distinction in reports.
 - Normal runs write private best-effort evidence under `~/.pi/agent/pi-flow-external/runs/` or `PI_FLOW_EXTERNAL_RUNS_DIR`. Records may still contain sensitive prompts, excerpts, and tool output despite redaction.
 - Structured nested-agent activity may extend the wall-clock deadline once, by one fresh base timeout, capped at twice the original deadline.
-- Do not automatically retry failed or aborted external runs. Preserve the receipt and retry only when the user asks.
+- Do not automatically retry failed or aborted external runs. Preserve the receipt and retry only when the user asks. Exception: the agy backend retries once on infrastructure-classified failures (auth, eligibility, network); the retry is disclosed in the receipt details (`retries`, `retryOf`) and never applies to agent-level failures, aborts, or timeouts.
 
 ## Workflow contract
 

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [1.3.0-external.0] - 2026-09-06
+
+Adds a bounded retry for the Antigravity backend and documents the standardized external profile role matrix.
+
+### Added
+
+- Single automatic retry for agy infrastructure failures (authentication, eligibility, network timeouts), disclosed in receipt details as `retries` and `retryOf`. Agent-level failures, aborts, and timeouts are never retried.
+
+### Changed
+
+- AGENTS.md records the agy retry exception to the no-auto-retry policy; CONTEXT.md documents the profile role-matrix design stance (guardrails define lanes, not methods) and the known one-file-per-backend format inelegance.
+
 ## [1.2.0-external.0] - 2026-08-29
 
 Implements the orchestrator-decided tiers design ([#11](https://github.com/tranhoangnguyen03/pi-flow-external/issues/11)), live-verified against Claude Code 2.1.239, codex-cli 0.150.1, and agy 1.1.22.

package/CONTEXT.md

@@ -28,6 +28,15 @@ The split is global and intentional to avoid tool ambiguity across projects. The
 
 User operations are namespaced under `/external`: status, Doctor, settings, profiles, profile creation, workflows, runs, and help. Extension-owned concurrency and timeout defaults live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`; profiles remain authoritative for downstream backend/model/thinking metadata.
 
+## Design stance
+
+Guardrails exist to keep lanes from bleeding into each other (a reviewer that edits, a debugger that fixes), not to constrain how a model works. Role bodies stay short: define the job, state the boundary, then get out of the way and trust the model's judgment on approach, depth, and method. The generic `worker` role covers non-coding tasks with no method constraints at all.
+
+## Known inelegance
+
+<!-- ponytail: one-backend-per-file profile format forces role x backend file duplication; extend src/profiles.ts with multi-backend profiles (e.g. backends: [claude, codex, agy] plus per-backend model map) if maintaining N copies of identical role bodies ever hurts -->
+A standardized role roster needs one file per role per backend (e.g. `claude-qa`, `codex-qa`, `agy-qa` with identical bodies) because the profile format binds `backend:` and `model:` to a single file. The duplication is accepted for now; a future format extension could let one role file cover all backends. The same applies to `permission:` tiers: one tier per profile, but backends interpret tiers differently (Claude denies Bash at anything below `danger`), so command-running roles must declare `danger` even where a finer tier exists.
+
 ## Evidence boundary
 
-Normal external runs write best-effort local records under `~/.pi/agent/pi-flow-external/runs/` unless `PI_FLOW_EXTERNAL_RUNS_DIR` overrides it. The TUI shows short evidence IDs by default and exposes record/journal paths only through expanded output. Redaction is best-effort, records are not rotated automatically, and failed/aborted runs are not retried automatically.
+Normal external runs write best-effort local records under `~/.pi/agent/pi-flow-external/runs/` unless `PI_FLOW_EXTERNAL_RUNS_DIR` overrides it. The TUI shows short evidence IDs by default and exposes record/journal paths only through expanded output. Redaction is best-effort, records are not rotated automatically, and failed/aborted runs are not retried automatically, except one agy retry for infrastructure-classified failures (disclosed via receipt `retries`/`retryOf`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "1.2.0-external.0",
+  "version": "1.3.0-external.0",
   "description": "External Claude Code, Codex CLI, and Antigravity delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/agy.ts

@@ -237,6 +237,20 @@ function abortChild(child: ChildProcess): void {
   }, FORCE_KILL_DELAY_MS).unref();
 }
 
+/** Infra-classified agy failures worth one bounded retry (auth/eligibility/network).
+ * Agent-level failures (task errors, protocol errors, aborts, timeouts) must not match. */
+const TRANSIENT_AGY_FAILURE_PATTERNS: RegExp[] = [
+  /authentication failed/i,
+  /eligibility check failed/i,
+  /operation timed out/i,
+  /\b(ETIMEDOUT|ECONNRESET|ECONNREFUSED|ENOTFOUND|EAI_AGAIN)\b/,
+];
+
+export function isTransientAgyFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return TRANSIENT_AGY_FAILURE_PATTERNS.some((pattern) => pattern.test(message));
+}
+
 export async function spawnAgySubagent(params: {
   toolCallId: string;
   description: string;

package/src/core/spawn.ts

@@ -19,7 +19,7 @@ import {
 } from "./progress.ts";
 import { spawnClaudeSubagent } from "./claude.ts";
 import { spawnCodexSubagent } from "./codex.ts";
-import { spawnAgySubagent } from "./agy.ts";
+import { spawnAgySubagent, isTransientAgyFailure } from "./agy.ts";
 import type {
   PermissionTier,
   SubagentBackend,
@@ -281,6 +281,8 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
           ? { budgetEnforceable: false }
           : {}),
         ...(details.sessionId ? { sessionId: details.sessionId } : {}),
+        ...(details.retries !== undefined ? { retries: details.retries } : {}),
+        ...(details.retryOf ? { retryOf: details.retryOf } : {}),
         ...(resumeSession ? { resumedFrom: resumeSession.runId } : {}),
       });
       attachRunRecord(
@@ -341,7 +343,8 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
     });
   }
   if (params.profile.backend === "agy") {
-    return spawnAgySubagent({
+    // ponytail: one immediate retry, agy-only, infra-classified failures only; per-attempt backoff if flakes persist
+    const agyParams = {
       toolCallId: params.toolCallId,
       description: params.description,
       prompt: params.prompt,
@@ -357,7 +360,25 @@ async function spawnSubagentRuntime(params: SpawnSubagentRuntimeParams): Promise
       outputSchema: params.outputSchema,
       permission: params.permission,
       resumeConversationId: params.resumeSessionId,
-    });
+    };
+    let retryOf: string | undefined;
+    for (let attempt = 1; ; attempt++) {
+      const result = await spawnAgySubagent(agyParams);
+      const details = result.details as SubagentToolDetails;
+      const transientFailure =
+        details.status === "error" && !params.signal?.aborted && isTransientAgyFailure(details.error);
+      if (transientFailure && attempt === 1) {
+        retryOf = details.error ?? "agy transient failure";
+        // Resume the failed conversation so a mid-turn network failure does not
+        // replay already-executed tool calls in a fresh conversation.
+        agyParams.resumeConversationId = details.sessionId ?? agyParams.resumeConversationId;
+        continue;
+      }
+      if (retryOf) {
+        return { ...result, details: { ...details, retries: attempt - 1, retryOf } };
+      }
+      return result;
+    }
   }
   if (params.profile.backend === "claude") {
     return spawnClaudeSubagent({

package/src/types.ts

@@ -191,6 +191,10 @@ export interface SubagentToolDetails {
   recordingError?: string;
   /** Number of currently running subagents, used to choose rich vs compact live rendering. */
   activeCount?: number;
+  /** Attempts retried for this run (agy infra failures retry once). */
+  retries?: number;
+  /** Error message of the retried-away first attempt, for transparency. */
+  retryOf?: string;
   frame?: number;
   /** Resolved permission tier for this run. */
   permission?: PermissionTier;