@tranhoangnguyen0310/pi-flow-external 2.7.0-external.0 → 2.8.0-external.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.8.0-external.0] - 2026-09-24
+
+### Added
+- Expand `/external doctor` with CLI readiness, supported login-status checks, and secret-safe inherited authentication-setting warnings.
+- Report project-scoped historical usage-limit evidence from retained summaries, including reset times and later successful runs. Capture new Claude structured rejections and Antigravity terminal quota errors without live quota probes.
+
 ## [2.7.0-external.0] - 2026-09-24
 
 ### Added

package/README.md

@@ -189,7 +189,9 @@ All user commands use the `/external` namespace:
 | `/external runs --prune` | Prune eligible completed run records |
 | `/external help` | Show the command reference |
 
-`/external doctor` reports CLI availability separately from provider authentication, and separately from whether the catalog itself is valid.
+`/external doctor` reports CLI availability separately from provider authentication and catalog validity. Claude and Codex use their non-interactive login-status commands; other CLIs report login as unverified. Credential presence does not prove a request will succeed. Known inherited authentication/routing environment variables are listed by name only, never value. Native status commands may access credential storage or perform network activity; no model prompts or quota requests are sent, and no credentials are changed.
+
+Doctor also reads retained run summaries for this project and shows the latest recorded usage-limit observation per harness, its source run, any reset time, and whether a later run succeeded. These are historical observations, not current account status. New failed Claude runs can preserve structured rate-limit rejections; Antigravity runs can preserve terminal individual-quota errors. Other backends and older records may have no evidence. Missing, malformed, or oversized summaries are skipped and counted; backend event logs and model answers are never searched. Remaining allowance stays unavailable.
 
 A typical overview:
 

package/package.json

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

package/src/core/spawn.ts

@@ -344,10 +344,12 @@ export function createPiChildResourceLoader(options: {
     appendSystemPromptOverride: (base) => [...base, ...extra],
   });
 }
+import { usageLimitFromEvent, type UsageLimit } from "./usage-limit.ts";
 
 export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentToolResult> {
   const startedAt = Date.now();
   let backendEventCount = 0;
+  let usageLimit: UsageLimit | undefined;
   let nestedActivitySeen = false;
   const effectiveTier = resolveEffectivePermissionTier(params.permission, params.profile, params.defaultPermission ?? "danger");
   const permission = resolvePermission(effectiveTier, params.profile.backend);
@@ -410,6 +412,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
   const timeout = createTimeoutSignal(params.signal, params.timeoutMs, params.description);
   const onBackendEvent = (event: unknown) => {
     backendEventCount++;
+    usageLimit = usageLimitFromEvent(params.profile.backend, event) ?? usageLimit;
     const hadNestedActivity = nestedActivitySeen;
     try {
       nestedActivitySeen ||= hasNestedAgentActivity(event, params.profile.backend);
@@ -490,6 +493,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
         firstActivityAt: details.progress?.firstActivityAt,
         lastActivityAt: details.progress?.lastActivityAt,
         error: details.error,
+        ...(details.status === "error" && usageLimit ? { usageLimit } : {}),
         usage: details.usage,
         durationMs: Date.now() - startedAt,
         backendEventCount,

package/src/core/usage-limit.ts

@@ -0,0 +1,23 @@
+export interface UsageLimit {
+  source: "claude.rate_limit_event" | "agy.result.error";
+  observedAt: string;
+  resetsAt?: string;
+}
+
+export function usageLimitFromEvent(backend: string, value: unknown, now = Date.now()): UsageLimit | undefined {
+  if (!value || typeof value !== "object") return;
+  const event = value as Record<string, unknown>;
+  let source: UsageLimit["source"];
+  let reset: number | undefined;
+  if (backend === "claude" && event.type === "rate_limit_event") {
+    const info = event.rate_limit_info as Record<string, unknown> | undefined;
+    if (!info || info.status !== "rejected") return;
+    source = "claude.rate_limit_event";
+    if (typeof info.resetsAt === "number") reset = info.resetsAt * 1000;
+  } else if (backend === "agy" && event.type === "result" && event.status === "ERROR" && typeof event.error === "string" && /\bIndividual quota reached\b/i.test(event.error)) {
+    source = "agy.result.error";
+    const duration = /Resets in (?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?\./i.exec(event.error);
+    if (duration && duration.slice(1).some(Boolean)) reset = now + ((Number(duration[1] ?? 0) * 3600) + (Number(duration[2] ?? 0) * 60) + Number(duration[3] ?? 0)) * 1000;
+  } else return;
+  return { source, observedAt: new Date(now).toISOString(), ...(reset !== undefined && Number.isFinite(reset) && Math.abs(reset) <= 8.64e15 ? { resetsAt: new Date(reset).toISOString() } : {}) };
+}

package/src/doctor.ts

@@ -0,0 +1,114 @@
+import { open, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Summary-only, bounded reads: never scan potentially huge backend event logs.
+export async function usageLimitHistory(directory: string, project: string, now = Date.now()): Promise<string> {
+  const latest = new Map<string, { time: number; runId: string; reset?: number }>();
+  const successes = new Map<string, number>();
+  let skipped = 0;
+  let entries;
+  try { entries = await readdir(directory, { withFileTypes: true }); }
+  catch { return "Usage-limit history: unavailable (run records could not be read)."; }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !/^run_[A-Za-z0-9_-]{1,128}$/.test(entry.name)) continue;
+    let file;
+    try {
+      file = await open(join(directory, entry.name, "summary.json"), "r");
+      const buffer = Buffer.alloc(256 * 1024 + 1);
+      let length = 0;
+      while (length < buffer.length) {
+        const { bytesRead } = await file.read(buffer, length, buffer.length - length, null);
+        if (!bytesRead) break;
+        length += bytesRead;
+      }
+      if (length === buffer.length) { skipped++; continue; }
+      const doc = JSON.parse(buffer.subarray(0, length).toString("utf8"));
+      if (doc?.runId !== entry.name) { skipped++; continue; }
+      const cwd = doc.metadata?.project ?? doc.metadata?.cwd;
+      if (typeof cwd !== "string" || resolve(cwd) !== resolve(project)) continue;
+      const summary = doc.summary;
+      const harness = doc.metadata?.harness ?? summary?.backend;
+      if (typeof harness !== "string" || !/^(claude|codex|agy|grok|muse|pi-[a-z0-9-]+)$/.test(harness)) continue;
+      const finished = Date.parse(doc.finishedAt);
+      if (summary?.status === "done" && Number.isFinite(finished)) successes.set(harness, Math.max(successes.get(harness) ?? 0, finished));
+      const limit = summary?.usageLimit;
+      if (summary?.status !== "error" || !limit || !["claude.rate_limit_event", "agy.result.error"].includes(limit.source)) continue;
+      if (limit.source !== `${summary.backend}.${summary.backend === "claude" ? "rate_limit_event" : "result.error"}`) continue;
+      const time = Date.parse(limit.observedAt);
+      if (!Number.isFinite(time) || time > now) continue;
+      const reset = typeof limit.resetsAt === "string" ? Date.parse(limit.resetsAt) : NaN;
+      if (!latest.has(harness) || latest.get(harness)!.time < time) latest.set(harness, { time, runId: entry.name, ...(Number.isFinite(reset) ? { reset } : {}) });
+    } catch { skipped++; }
+    finally { await file?.close(); }
+  }
+  const lines = ["Usage-limit history (this project only; not a live account check):"];
+  for (const [harness, limit] of latest) {
+    const success = successes.get(harness);
+    lines.push(`  ${harness}: limit reported ${new Date(limit.time).toISOString()} · ${limit.runId}${limit.reset === undefined ? "" : ` · reset ${new Date(limit.reset).toISOString()}${limit.reset <= now ? " (time passed)" : ""}`}${success !== undefined && success > limit.time ? " · a later run succeeded" : ""}. Current availability unverified.`);
+  }
+  if (!latest.size) lines.push("  No recorded limit evidence found. This does not mean allowance is available.");
+  lines.push("  New Claude/Antigravity records can report limits; other backends and older records may not. Retained records only.");
+  if (skipped) lines.push(`  ${skipped} missing, oversized, or unreadable summaries skipped.`);
+  return lines.join("\n");
+}
+
+// Names only: values and raw CLI diagnostics can contain credentials.
+const ENV_WARNINGS: Record<string, string[]> = {
+  claude: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_BASE_URL", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"],
+  codex: ["CODEX_API_KEY", "OPENAI_API_KEY", "OPENAI_BASE_URL", "CODEX_HOME"],
+  agy: [],
+  grok: ["XAI_API_KEY"],
+  muse: ["META_API_KEY"],
+};
+
+export async function diagnoseCli(exec: ExtensionAPI["exec"], backend: string, env: NodeJS.ProcessEnv = process.env): Promise<string> {
+  const lines = [`${backend}:`];
+  let available = false;
+  try {
+    const result = await exec(backend, ["--version"], { timeout: 10_000 });
+    available = result.code === 0 && !result.killed;
+    // Only display a version number, never echo arbitrary subprocess output.
+    const version = (result.stdout || result.stderr).match(/\b\d+\.\d+\.\d+\b/)?.[0];
+    lines.push(available
+      ? `  CLI: available${version ? ` (${backend} ${version})` : ""}`
+      : result.killed ? "  CLI: version check timed out" : "  CLI: could not start; check the installation with --version");
+  } catch (error) {
+    lines.push(error && typeof error === "object" && "code" in error && error.code === "ENOENT"
+      ? "  CLI: not found; install it or check PATH"
+      : "  CLI: check failed; check the installation with --version");
+  }
+
+  let login = "not verified (no supported status check)";
+  if (!available) login = "not checked (CLI unavailable)";
+  else if (backend === "claude" || backend === "codex") {
+    try {
+      const result = await exec(backend, backend === "claude" ? ["auth", "status", "--json"] : ["login", "status"], { timeout: 10_000 });
+      login = result.killed ? "not verified (status check timed out)" : "not verified (status check failed)";
+      if (!result.killed) {
+        if (backend === "claude") {
+          let status: unknown;
+          try { status = JSON.parse(result.stdout); } catch { /* Unknown output stays unverified. */ }
+          const loggedIn = status && typeof status === "object" && "loggedIn" in status ? status.loggedIn : undefined;
+          if (loggedIn === false) login = "no login reported; use claude auth login if account login is intended";
+          else if (result.code === 0) login = loggedIn === true ? "login reported by CLI; requests not tested" : "not verified (unrecognized status)";
+        } else {
+          const text = (result.stderr || result.stdout).trim();
+          if (text === "Not logged in") login = "no login reported; use codex login if account login is intended";
+          else if (result.code === 0) login = text === "Logged in using ChatGPT"
+            ? "ChatGPT login reported by CLI; requests not tested"
+            : /^Logged in using an API key(?: - [^\r\n]*)?$/.test(text)
+              ? "API key login reported by CLI; requests not tested"
+              : "not verified (unrecognized status)";
+        }
+      }
+    } catch {
+      login = "not verified (status check failed)";
+    }
+  }
+  lines.push(`  Login: ${login}`);
+  const set = (ENV_WARNINGS[backend] ?? []).filter(name => Boolean(env[name]));
+  if (set.length) lines.push(`  Settings: ${set.join(", ")} set; inherited by child and may affect authentication or routing. Values hidden.`);
+  lines.push("  Remaining allowance: unavailable (no quota request made)");
+  return lines.join("\n");
+}

package/src/external-command.ts

@@ -24,6 +24,7 @@ import { pruneRunRecords, runRecordsDirectory } from "./core/retention.ts";
 import { createExternalRunsTool, type ExternalRunsParams } from "./external-runs.ts";
 import { formatDurationMs, formatRunRow } from "./core/run-render.ts";
 import { listSavedWorkflows } from "./workflow/registry.ts";
+import { diagnoseCli, usageLimitHistory } from "./doctor.ts";
 
 const COMMANDS = [
   { value: "doctor", description: "Validate config/catalog and report runtime readiness" },
@@ -542,11 +543,7 @@ async function doctorText(pi: ExtensionAPI, options: ExternalCommandOptions, ctx
     profiles.size ? `✓ Roles: ${profiles.size} execution identities` : "✗ Roles: none configured",
   ];
   for (const backend of backends) {
-    const result = await pi.exec(backend, ["--version"], { timeout: 10_000 });
-    const version = (result.stdout || result.stderr).trim().split(/\r?\n/, 1)[0];
-    lines.push(result.code === 0 && !result.killed
-      ? `✓ ${backend}: ${version || "available"} (authentication unverified)`
-      : `✗ ${backend}: unavailable`);
+    lines.push(await diagnoseCli(pi.exec.bind(pi), backend));
   }
   // Pi harnesses run in-process, not as a CLI: there is no subprocess to exec.
   // Confirm the registered model resolves and report configured auth instead.
@@ -561,7 +558,9 @@ async function doctorText(pi: ExtensionAPI, options: ExternalCommandOptions, ctx
     lines.push(ctx.modelRegistry.hasConfiguredAuth(model)
       ? `✓ ${name}: ${config.model} · ${preset} (auth configured)`
       : `⚠ ${name}: ${config.model} · ${preset} (no credentials configured)`);
+    lines.push("  Requests not tested; provider authentication/routing follows Pi configuration.", "  Remaining allowance: unavailable (no quota request made)");
   }
+  lines.push(await usageLimitHistory(runRecordsDirectory(), ctx.cwd));
   return lines.join("\n");
 }