@tea-agent/loop-agent 0.1.0-fe-test.0

package/dist/commands/client-recovery.js

@@ -0,0 +1,1373 @@
+import { mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const CLIENT_RECOVERY_MODES = [
+    "auto",
+    "project",
+    "user",
+    "off",
+];
+export const OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH = ".opencode/plugins/loop-agent-transient-retry.js";
+export const OPENCODE_TRANSIENT_RETRY_LOG_PATH = ".opencode/plugins/loop-agent-transient-retry.log";
+export const OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH = ".opencode/plugins/loop-agent-context-overflow-compact.js";
+export const PI_CONTEXT_OVERFLOW_EXTENSION_PATH = ".pi/extensions/loop-agent-context-overflow.js";
+/** Pi project settings are part of the managed init surface; never default to home. */
+export const PI_PROJECT_SETTINGS_PATH = ".pi/settings.json";
+export const PERMANENT_ERROR_INTERACTION = "plugin-ignore-permanent-error";
+export const BACKOFF_MS = [2000, 4000, 8000, 16000, 30000];
+export const MAX_SESSION_RETRIES = 5;
+/** Hard cap for OpenCode overflow compact+resume recoveries (≤ 2). */
+export const MAX_OVERFLOW_RECOVERIES = 1;
+import { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY, } from "../shared/pi-retry-settings.js";
+export { PI_RECOMMENDED_COMPACTION, PI_RECOMMENDED_RETRY };
+/**
+ * Shared overflow phrase sources used by isContextOverflow and generated plugins.
+ * Keep English + Chinese intranet gateway messages in one place to avoid drift.
+ */
+export const CONTEXT_OVERFLOW_PHRASES = [
+    "请求上下文过大",
+    "context_length_exceeded",
+    "context overflow",
+    "context length overflow",
+    "too many tokens",
+    "maximum context",
+    "prompt is too long",
+    "request_too_large",
+    "context window",
+];
+function escapeRegExpLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const CONTEXT_OVERFLOW_PATTERN = new RegExp(CONTEXT_OVERFLOW_PHRASES.map(escapeRegExpLiteral).join("|"), "i");
+function buildGeneratedContextOverflowPatternSource() {
+    return `const CONTEXT_OVERFLOW_PHRASES = ${JSON.stringify([
+        ...CONTEXT_OVERFLOW_PHRASES,
+    ])};
+const OVERFLOW_PATTERN = new RegExp(
+  CONTEXT_OVERFLOW_PHRASES.map((phrase) =>
+    phrase.replace(/[.*+?^\${}()|[\\]\\\\]/g, "\\\\$&"),
+  ).join("|"),
+  "i",
+);`;
+}
+const PERMANENT_MESSAGE_PATTERNS = [
+    {
+        reason: "auth",
+        pattern: /\b(401|unauthorized|invalid api key|authentication)\b/i,
+    },
+    {
+        reason: "permission",
+        pattern: /\b(403|forbidden|permission denied|not allowed)\b/i,
+    },
+    {
+        reason: "quota",
+        pattern: /\b(quota|rate.?limit|billing|insufficient.?credit)\b/i,
+    },
+    {
+        reason: "context-overflow",
+        pattern: CONTEXT_OVERFLOW_PATTERN,
+    },
+    {
+        reason: "cancelled",
+        pattern: /\b(cancelled|canceled|aborted by user|user cancel)\b/i,
+    },
+    {
+        reason: "business-validation",
+        pattern: /\b(business validation|invalid task|schema validation)\b/i,
+    },
+];
+const TRANSIENT_MESSAGE_PATTERNS = [
+    /\bcode[:\s]*502\b/i,
+    /\b502\b/,
+    /\bLLMRequestError\b/i,
+    /\bnetwork fluctuation\b/i,
+    /\btimeout\b/i,
+    /\btransient provider failure\b/i,
+    /\bnon-standard (payload|response)\b/i,
+    /\bupstream returned\b/i,
+    /\bmodel processing timeout\b/i,
+];
+export function isClientRecoveryMode(value) {
+    return (typeof value === "string" &&
+        CLIENT_RECOVERY_MODES.includes(value));
+}
+export function parseClientRecoveryMode(value) {
+    if (value === undefined || value === null || value === "")
+        return "auto";
+    if (isClientRecoveryMode(value))
+        return value;
+    throw new Error(`init --client-recovery must be one of ${CLIENT_RECOVERY_MODES.join("|")}`);
+}
+function asText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function collectErrorText(error) {
+    if (typeof error === "string")
+        return error;
+    if (!error || typeof error !== "object")
+        return asText(error);
+    const record = error;
+    const parts = [
+        asText(record.name),
+        asText(record.message),
+        asText(record.status),
+        asText(record.code),
+        asText(record.data),
+    ];
+    return parts.filter(Boolean).join(" ");
+}
+function hasUnknownErrorShape(error) {
+    const text = collectErrorText(error);
+    if (/\bUnknownError\b/i.test(text))
+        return true;
+    if (error && typeof error === "object") {
+        const record = error;
+        if (typeof record.name === "string" && /UnknownError/i.test(record.name))
+            return true;
+    }
+    return false;
+}
+/**
+ * TypeValidation bypass shape: bare TypeValidationError (zod invalid_union
+ * surfaced directly by the provider/SDK instead of wrapped as UnknownError).
+ * Bypass only fires when combined with a transient signal (see classifyTransientUnknownError).
+ */
+function hasTypeValidationShape(error) {
+    const text = collectErrorText(error);
+    if (/\bTypeValidationError\b/i.test(text))
+        return true;
+    if (/Type validation failed/i.test(text))
+        return true;
+    if (error && typeof error === "object") {
+        const record = error;
+        if (typeof record.name === "string" &&
+            /TypeValidationError/i.test(record.name)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isStandardApiError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const record = error;
+    if (typeof record.name === "string" && /^APIError$/i.test(record.name))
+        return true;
+    if (typeof record.name === "string" &&
+        /^(AuthError|PermissionError)$/i.test(record.name)) {
+        return true;
+    }
+    return false;
+}
+function permanentReason(error) {
+    if (isStandardApiError(error)) {
+        const record = error;
+        if (typeof record.name === "string" && /AuthError/i.test(record.name))
+            return "auth";
+        if (typeof record.name === "string" &&
+            /PermissionError/i.test(record.name)) {
+            return "permission";
+        }
+        return "api-error";
+    }
+    const text = collectErrorText(error);
+    for (const entry of PERMANENT_MESSAGE_PATTERNS) {
+        if (entry.pattern.test(text))
+            return entry.reason;
+    }
+    return undefined;
+}
+/**
+ * Shared context-overflow recognition for OpenCode overflow-compact plugin,
+ * Pi project extension, and pure tests. Does not treat 401/403, quota, cancel,
+ * business validation, or standard 502/LLMRequestError as overflow.
+ */
+export function isContextOverflow(error) {
+    return CONTEXT_OVERFLOW_PATTERN.test(collectErrorText(error));
+}
+function looksTransient(error) {
+    const text = collectErrorText(error);
+    if (TRANSIENT_MESSAGE_PATTERNS.some((pattern) => pattern.test(text)))
+        return true;
+    if (error && typeof error === "object") {
+        const record = error;
+        if (record.code === 502 || record.status === 502)
+            return true;
+        if (record.data && typeof record.data === "object") {
+            const data = record.data;
+            if (data.code === 502 || data.status === 502)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide whether an OpenCode error should be resumed by the project plugin.
+ * Only compensates transient UnknownError paths that built-in APIError retry misses.
+ *
+ * TypeValidation bypass: a bare TypeValidationError (provider/SDK surfaces
+ * zod invalid_union directly, without the UnknownError wrapper) is treated as
+ * a retryable transient-unknown-error ONLY when it also carries a transient
+ * signal (502 / LLMRequestError / timeout / etc.). A pure schema mismatch
+ * without a transient signal is still rejected (resumable: false).
+ */
+export function classifyTransientUnknownError(error) {
+    const permanent = permanentReason(error);
+    if (permanent) {
+        return {
+            resumable: false,
+            reason: permanent,
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    const isUnknownShape = hasUnknownErrorShape(error);
+    const isTypeValidationShape = hasTypeValidationShape(error);
+    if (!isUnknownShape && !isTypeValidationShape) {
+        return {
+            resumable: false,
+            reason: "not-unknown-error",
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    if (!looksTransient(error)) {
+        return {
+            resumable: false,
+            reason: "unknown-non-transient",
+            interaction: PERMANENT_ERROR_INTERACTION,
+        };
+    }
+    return { resumable: true, reason: "transient-unknown-error" };
+}
+export function nextBackoffMs(attempt) {
+    if (!Number.isInteger(attempt) ||
+        attempt < 0 ||
+        attempt >= BACKOFF_MS.length) {
+        return undefined;
+    }
+    return BACKOFF_MS[attempt];
+}
+export function canResumeSession(input) {
+    if (input.sessionStatus === "retry") {
+        return { allowed: false, reason: "builtin-retry-active" };
+    }
+    if (!input.sessionStatus) {
+        return { allowed: false, reason: "session-status-unknown" };
+    }
+    if (input.locked) {
+        return { allowed: false, reason: "session-locked" };
+    }
+    if (!input.idle ||
+        input.sessionStatus === "busy" ||
+        input.sessionStatus === "running") {
+        return { allowed: false, reason: "session-busy" };
+    }
+    if (input.attempt >= MAX_SESSION_RETRIES) {
+        return { allowed: false, reason: "max-retries" };
+    }
+    return { allowed: true, reason: "ready" };
+}
+export function buildResumePrompt(input) {
+    return [
+        `[loop-agent transient recovery] session=${input.sessionId} attempt=${input.attempt}`,
+        `Previous model turn failed with a transient UnknownError: ${input.errorSummary}`,
+        "Before continuing any work, first inspect already completed tool calls and existing file modifications in this session.",
+        "Do not re-run side-effecting tools or rewrite files that already reflect successful prior work.",
+        "Resume only the remaining unfinished work after that check.",
+        "续接前请先检查本 session 已有工具调用与文件改动，避免重复执行有副作用的操作。",
+    ].join("\n");
+}
+export function createSessionRecoveryTracker() {
+    const states = new Map();
+    function getOrCreate(sessionId) {
+        let state = states.get(sessionId);
+        if (!state) {
+            state = { attempt: 0, locked: false };
+            states.set(sessionId, state);
+        }
+        return state;
+    }
+    return {
+        getOrCreate,
+        isLocked(sessionId) {
+            return getOrCreate(sessionId).locked;
+        },
+        tryAcquire(sessionId) {
+            const state = getOrCreate(sessionId);
+            if (state.locked)
+                return false;
+            state.locked = true;
+            return true;
+        },
+        release(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.locked = false;
+        },
+        markSuccess(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.attempt = 0;
+            state.locked = false;
+        },
+        incrementAttempt(sessionId) {
+            const state = getOrCreate(sessionId);
+            state.attempt += 1;
+            return state.attempt;
+        },
+    };
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readRetryEnabled(existing) {
+    if (!existing || !isRecord(existing.retry))
+        return undefined;
+    if (typeof existing.retry.enabled !== "boolean")
+        return undefined;
+    return existing.retry.enabled;
+}
+/**
+ * Field-level plan for ~/.pi/agent/settings.json retry recommendations.
+ * Never clobbers existing values; never overrides enabled:false.
+ */
+export function planPiRetryMerge(existing) {
+    const settingsPath = "~/.pi/agent/settings.json";
+    if (existing === undefined) {
+        return {
+            action: "write",
+            reason: "missing-file",
+            path: settingsPath,
+            next: {
+                retry: {
+                    ...PI_RECOMMENDED_RETRY,
+                    provider: { ...PI_RECOMMENDED_RETRY.provider },
+                },
+            },
+        };
+    }
+    if (!isRecord(existing)) {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            message: "Pi settings root must be a JSON object",
+        };
+    }
+    const enabled = readRetryEnabled(existing);
+    if (enabled === false) {
+        return {
+            action: "report",
+            reason: "enabled-false",
+            path: settingsPath,
+            next: existing,
+            message: "retry.enabled=false is preserved; human decision required to enable recovery",
+        };
+    }
+    const retry = isRecord(existing.retry) ? { ...existing.retry } : {};
+    const provider = isRecord(retry.provider) ? { ...retry.provider } : {};
+    let changed = !isRecord(existing.retry) ||
+        !isRecord(existing.retry.provider);
+    if (retry.enabled === undefined) {
+        retry.enabled = PI_RECOMMENDED_RETRY.enabled;
+        changed = true;
+    }
+    if (retry.maxRetries === undefined) {
+        retry.maxRetries = PI_RECOMMENDED_RETRY.maxRetries;
+        changed = true;
+    }
+    if (retry.baseDelayMs === undefined) {
+        retry.baseDelayMs = PI_RECOMMENDED_RETRY.baseDelayMs;
+        changed = true;
+    }
+    if (provider.maxRetries === undefined) {
+        provider.maxRetries = PI_RECOMMENDED_RETRY.provider.maxRetries;
+        changed = true;
+    }
+    if (provider.maxRetryDelayMs === undefined) {
+        provider.maxRetryDelayMs = PI_RECOMMENDED_RETRY.provider.maxRetryDelayMs;
+        changed = true;
+    }
+    retry.provider = provider;
+    const next = { ...existing, retry };
+    if (!changed) {
+        return {
+            action: "noop",
+            reason: "matches",
+            path: settingsPath,
+            next,
+        };
+    }
+    return {
+        action: "write",
+        reason: "missing-fields",
+        path: settingsPath,
+        next,
+    };
+}
+export function piSettingsPath(homeDir) {
+    return path.join(homeDir, ".pi", "agent", "settings.json");
+}
+async function writeJsonAtomic(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+        await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+export async function applyPiRetryMerge(input) {
+    const settingsPath = piSettingsPath(input.homeDir);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        raw = undefined;
+    }
+    if (raw === undefined) {
+        const plan = planPiRetryMerge(undefined);
+        if (plan.action === "write" && plan.next) {
+            await writeJsonAtomic(settingsPath, plan.next);
+            return { ...plan, path: settingsPath, wrote: true };
+        }
+        return { ...plan, path: settingsPath, wrote: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+            message: "Pi settings.json is not valid JSON; refusing to write",
+        };
+    }
+    if (!isRecord(parsed)) {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+            message: "Pi settings.json root must be a JSON object; refusing to write",
+        };
+    }
+    const plan = planPiRetryMerge(parsed);
+    if (plan.action === "write" && plan.next) {
+        await writeJsonAtomic(settingsPath, plan.next);
+        // Best-effort cleanup of any stray temp files from interrupted prior runs.
+        try {
+            const dir = path.dirname(settingsPath);
+            const entries = await readdir(dir);
+            await Promise.all(entries
+                .filter((name) => name.startsWith(`.${path.basename(settingsPath)}.`) &&
+                name.endsWith(".tmp"))
+                .map((name) => rm(path.join(dir, name), { force: true })));
+        }
+        catch {
+            // ignore cleanup failures
+        }
+        return { ...plan, path: settingsPath, wrote: true };
+    }
+    return { ...plan, path: settingsPath, wrote: false };
+}
+/**
+ * Stable generated source for the OpenCode project plugin.
+ * The plugin compensates only transient UnknownError after built-in retry is idle.
+ */
+export function buildOpenCodeTransientRetryPluginSource() {
+    // Keep this template deterministic: no timestamps, no random ids.
+    return `/**
+ * loop-agent OpenCode transient recovery plugin
+ * Path: ${OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH}
+ *
+ * Compensates transient UnknownError cases that OpenCode built-in APIError
+ * retry does not cover. Never runs concurrently with session.status === "retry".
+ * Permanent failures use interaction "${PERMANENT_ERROR_INTERACTION}".
+ * User aborts (MessageAbortedError / cancel words) are silently cleared.
+ * Best-effort file log: ${OPENCODE_TRANSIENT_RETRY_LOG_PATH}.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFile, mkdir } from "node:fs/promises";
+
+const PLUGIN_PATH = ${JSON.stringify(OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH)};
+const LOG_FILE_NAME = ${JSON.stringify(path.basename(OPENCODE_TRANSIENT_RETRY_LOG_PATH))};
+const LOG_PATH = (() => {
+  try {
+    const dir =
+      import.meta.dirname ?? path.dirname(fileURLToPath(import.meta.url));
+    return path.join(dir, LOG_FILE_NAME);
+  } catch {
+    return ${JSON.stringify(OPENCODE_TRANSIENT_RETRY_LOG_PATH)};
+  }
+})();
+const PERMANENT_INTERACTION = ${JSON.stringify(PERMANENT_ERROR_INTERACTION)};
+const BACKOFF_MS = ${JSON.stringify([...BACKOFF_MS])};
+const MAX_RETRIES = ${MAX_SESSION_RETRIES};
+${buildGeneratedContextOverflowPatternSource()}
+void logToFile("load ok");
+
+const sessionState = new Map();
+const sessionStatus = new Map();
+const pendingErrors = new Map();
+const recoveryWorkers = new Map();
+
+function getState(sessionId) {
+  let state = sessionState.get(sessionId);
+  if (!state) {
+    state = { attempt: 0, locked: false, rerunRequested: false };
+    sessionState.set(sessionId, state);
+  }
+  return state;
+}
+
+function textOf(error) {
+  if (!error) return "";
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+async function logToFile(line) {
+  try {
+    await mkdir(path.dirname(LOG_PATH), { recursive: true });
+    await appendFile(
+      LOG_PATH,
+      new Date().toISOString() + " " + line + "\\n",
+      "utf-8",
+    );
+  } catch {
+    // Best-effort observability log; never throw (ENOENT/EISDIR tolerated).
+  }
+}
+
+function isUserAbort(error) {
+  if (error && typeof error === "object" && typeof error.name === "string") {
+    if (/^MessageAbortedError$/i.test(error.name)) return true;
+  }
+  return /aborted by user|user cancel|cancelled|canceled/i.test(textOf(error));
+}
+
+function isPermanent(error) {
+  const text = textOf(error);
+  if (error && typeof error === "object" && typeof error.name === "string") {
+    if (/^APIError$/i.test(error.name)) return true;
+    if (/^(AuthError|PermissionError)$/i.test(error.name)) return true;
+  }
+  return (
+    OVERFLOW_PATTERN.test(text) ||
+    /\\b(401|403|unauthorized|forbidden|quota|rate.?limit|cancelled|canceled|business validation|invalid task|schema validation)\\b/i.test(text)
+  );
+}
+
+function isTransientUnknown(error) {
+  if (isPermanent(error)) return false;
+  const text = textOf(error);
+  const hasUnknown = /UnknownError/i.test(text) || (error && /UnknownError/i.test(String(error.name || "")));
+  const hasTypeValidation =
+    /\\bTypeValidationError\\b/i.test(text) ||
+    /Type validation failed/i.test(text) ||
+    (error && /TypeValidationError/i.test(String(error.name || "")));
+  if (!hasUnknown && !hasTypeValidation) return false;
+  return (
+    /\\b(code[:\\s]*502|502|LLMRequestError|network fluctuation|timeout|transient provider failure|non-standard)\\b/i.test(
+      text,
+    ) ||
+    (error && (error.code === 502 || error.status === 502))
+  );
+}
+
+function buildResumePrompt(sessionId, error, attempt) {
+  return [
+    "[loop-agent transient recovery] session=" + sessionId + " attempt=" + attempt,
+    "Previous model turn failed with a transient UnknownError: " + textOf(error),
+    "Before continuing any work, first inspect already completed tool calls and existing file modifications in this session.",
+    "Do not re-run side-effecting tools or rewrite files that already reflect successful prior work.",
+    "Resume only the remaining unfinished work after that check.",
+    "续接前请先检查本 session 已有工具调用与文件改动，避免重复执行有副作用的操作。",
+  ].join("\\n");
+}
+
+async function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function statusType(status) {
+  const type = status && typeof status.type === "string" ? status.type : undefined;
+  return type === "idle" || type === "retry" || type === "busy" ? type : undefined;
+}
+
+async function readSessionStatus(client, sessionId) {
+  const cached = sessionStatus.get(sessionId);
+  if (cached === "retry" || cached === "busy") {
+    return { ok: true, type: cached };
+  }
+  try {
+    const response = await client.session.status({ throwOnError: true });
+    if (!response || typeof response !== "object" || response.error != null) {
+      return { ok: false };
+    }
+    const current = statusType(response?.data?.[sessionId]);
+    if (!current) return { ok: false };
+    sessionStatus.set(sessionId, current);
+    return { ok: true, type: current };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function promptWasAccepted(response) {
+  return Boolean(
+    response &&
+      typeof response === "object" &&
+      response.error == null &&
+      Object.prototype.hasOwnProperty.call(response, "data") &&
+      response.data !== null &&
+      typeof response.data === "object",
+  );
+}
+
+export default async function loopAgentTransientRetryPlugin({ client, $ }) {
+  void $;
+  void PLUGIN_PATH;
+  void logToFile("setup ok");
+
+  async function drainPendingRecovery(sessionId) {
+    const state = getState(sessionId);
+    const pending = pendingErrors.get(sessionId);
+    if (!pending) return;
+    if (state.attempt >= MAX_RETRIES) {
+      pendingErrors.delete(sessionId);
+      return;
+    }
+
+    // A status event may be stale by the time this worker runs. Confirm idle via
+    // the SDK before and after backoff; every other outcome keeps the error pending.
+    const beforeDelay = await readSessionStatus(client, sessionId);
+    if (pendingErrors.get(sessionId) !== pending) return;
+    if (!beforeDelay.ok || beforeDelay.type !== "idle") return;
+
+    const delay = BACKOFF_MS[state.attempt];
+    if (typeof delay !== "number") {
+      pendingErrors.delete(sessionId);
+      return;
+    }
+    await wait(delay);
+    if (pendingErrors.get(sessionId) !== pending) return;
+
+    const beforePrompt = await readSessionStatus(client, sessionId);
+    if (pendingErrors.get(sessionId) !== pending) return;
+    if (!beforePrompt.ok || beforePrompt.type !== "idle") return;
+
+    const nextAttempt = state.attempt + 1;
+    const prompt = buildResumePrompt(sessionId, pending.error, nextAttempt);
+    let response;
+    try {
+      response = await client.session.promptAsync({
+        path: { id: sessionId },
+        body: { parts: [{ type: "text", text: prompt }] },
+        throwOnError: true,
+      });
+    } catch {
+      void logToFile(
+        "prompt attempt=" + nextAttempt + " accepted=false session=" + sessionId,
+      );
+      return;
+    }
+    const accepted = promptWasAccepted(response);
+    void logToFile(
+      "prompt attempt=" + nextAttempt + " accepted=" + accepted + " session=" + sessionId,
+    );
+    if (!accepted) return;
+
+    state.attempt = nextAttempt;
+    if (pendingErrors.get(sessionId) === pending) {
+      pendingErrors.delete(sessionId);
+    }
+  }
+
+  function startRecoveryWorker(sessionId) {
+    const state = getState(sessionId);
+    if (recoveryWorkers.has(sessionId)) {
+      state.rerunRequested = true;
+      return;
+    }
+    state.locked = true;
+    state.rerunRequested = false;
+    void logToFile("worker start session=" + sessionId);
+    const worker = drainPendingRecovery(sessionId)
+      .catch(() => {})
+      .finally(() => {
+        void logToFile("worker end session=" + sessionId);
+        recoveryWorkers.delete(sessionId);
+        const rerun = state.rerunRequested;
+        state.rerunRequested = false;
+        state.locked = false;
+        if (rerun && pendingErrors.has(sessionId)) {
+          startRecoveryWorker(sessionId);
+        }
+      });
+    recoveryWorkers.set(sessionId, worker);
+  }
+
+  function clearSession(sessionId) {
+    pendingErrors.delete(sessionId);
+    sessionStatus.delete(sessionId);
+    const state = sessionState.get(sessionId);
+    if (state) {
+      state.attempt = 0;
+      state.rerunRequested = false;
+      if (!recoveryWorkers.has(sessionId)) state.locked = false;
+    }
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (!event || typeof event !== "object") return;
+      const properties = event.properties || {};
+      const sessionId =
+        properties.sessionID || properties.sessionId || properties.id || properties.info?.id;
+
+      if (event.type === "session.status") {
+        const current = statusType(properties.status);
+        if (sessionId && current) sessionStatus.set(sessionId, current);
+        if (sessionId && current === "idle" && pendingErrors.has(sessionId)) {
+          startRecoveryWorker(sessionId);
+        }
+        return;
+      }
+
+      if (event.type === "session.idle") {
+        if (sessionId) {
+          sessionStatus.set(sessionId, "idle");
+          if (pendingErrors.has(sessionId)) startRecoveryWorker(sessionId);
+        }
+        return;
+      }
+
+      if (event.type === "session.deleted") {
+        if (sessionId) clearSession(sessionId);
+        return;
+      }
+
+      if (event.type === "message.updated") {
+        const info = properties.info;
+        if (
+          info?.role === "assistant" &&
+          info.sessionID &&
+          (info.status === undefined || info.status === "completed") &&
+          info.time?.completed != null &&
+          info.error == null
+        ) {
+          clearSession(info.sessionID);
+        }
+        return;
+      }
+
+      if (event.type === "session.error") {
+        if (!sessionId) return;
+        const error = properties.error || properties;
+        if (isUserAbort(error)) {
+          clearSession(sessionId);
+          void logToFile("classify abort session=" + sessionId);
+          return undefined;
+        }
+        if (!isTransientUnknown(error)) {
+          pendingErrors.delete(sessionId);
+          getState(sessionId).rerunRequested = false;
+          void logToFile("classify permanent session=" + sessionId);
+          return { interaction: PERMANENT_INTERACTION, reason: "plugin-ignore-permanent-error" };
+        }
+        pendingErrors.set(sessionId, { error });
+        void logToFile("classify transient session=" + sessionId);
+        startRecoveryWorker(sessionId);
+        return { pending: true };
+      }
+    },
+  };
+}
+`;
+}
+async function installGeneratedProjectFile(input) {
+    const target = path.join(input.repoRoot, input.relativePath);
+    if (input.onlyIfMissing) {
+        try {
+            await readFile(target, "utf-8");
+            return {
+                path: input.relativePath,
+                written: false,
+                reason: "unchanged",
+            };
+        }
+        catch {
+            // missing → write
+        }
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, input.content, "utf-8");
+    return { path: input.relativePath, written: true, reason: "written" };
+}
+export async function installProjectOpenCodePlugin(input) {
+    return installGeneratedProjectFile({
+        repoRoot: input.repoRoot,
+        relativePath: OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH,
+        content: buildOpenCodeTransientRetryPluginSource(),
+        onlyIfMissing: input.onlyIfMissing,
+    });
+}
+/**
+ * Stable generated source for the OpenCode context-overflow compact plugin.
+ * Separate from transient-retry: only overflow → compact/summarize + limited resume.
+ */
+export function buildOpenCodeContextOverflowCompactPluginSource() {
+    return `/**
+ * loop-agent OpenCode context overflow compact plugin
+ * Path: ${OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH}
+ *
+ * On context overflow (including Chinese "请求上下文过大"), compact/summarize
+ * then resume the same session a limited number of times. Does NOT handle
+ * provider transport / 502 recovery (that is loop-agent-transient-retry.js).
+ */
+const PLUGIN_PATH = ${JSON.stringify(OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH)};
+const MAX_OVERFLOW_RECOVERIES = ${MAX_OVERFLOW_RECOVERIES};
+${buildGeneratedContextOverflowPatternSource()}
+
+const sessionState = new Map();
+const sessionStatus = new Map();
+const pendingOverflow = new Map();
+const deferredResume = new Map();
+const recoveryWorkers = new Map();
+
+function getState(sessionId) {
+  let state = sessionState.get(sessionId);
+  if (!state) {
+    state = {
+      attempt: 0,
+      locked: false,
+      rerunRequested: false,
+      deferredIdleConfirmed: false,
+    };
+    sessionState.set(sessionId, state);
+  }
+  return state;
+}
+
+function textOf(error) {
+  if (!error) return "";
+  if (typeof error === "string") return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+function isContextOverflow(error) {
+  return OVERFLOW_PATTERN.test(textOf(error));
+}
+
+function buildOverflowResumePrompt(sessionId, error, attempt) {
+  return [
+    "[loop-agent context overflow recovery] session=" + sessionId + " attempt=" + attempt,
+    "Previous model turn failed because the request context was too large: " + textOf(error),
+    "Session history was compacted/summarized before this resume.",
+    "Before continuing any work, first inspect already completed tool calls and existing file modifications in this session.",
+    "Do not re-run side-effecting tools or rewrite files that already reflect successful prior work.",
+    "Resume only the remaining unfinished work after that check.",
+    "续接前请先检查本 session 已有工具调用与文件改动，避免重复执行有副作用的操作。",
+  ].join("\\n");
+}
+
+function statusType(status) {
+  const type = status && typeof status.type === "string" ? status.type : undefined;
+  return type === "idle" || type === "retry" || type === "busy" ? type : undefined;
+}
+
+async function readSessionStatus(client, sessionId) {
+  const cached = sessionStatus.get(sessionId);
+  if (cached === "retry" || cached === "busy") {
+    return { ok: true, type: cached };
+  }
+  try {
+    const response = await client.session.status({ throwOnError: true });
+    if (!response || typeof response !== "object" || response.error != null) {
+      return { ok: false };
+    }
+    const current = statusType(response?.data?.[sessionId]);
+    if (!current) return { ok: false };
+    sessionStatus.set(sessionId, current);
+    return { ok: true, type: current };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function promptWasAccepted(response) {
+  return Boolean(
+    response &&
+      typeof response === "object" &&
+      response.error == null &&
+      Object.prototype.hasOwnProperty.call(response, "data") &&
+      response.data !== null &&
+      typeof response.data === "object",
+  );
+}
+
+async function compactOrSummarize(client, sessionId) {
+  const body = { path: { id: sessionId }, throwOnError: true };
+  if (typeof client.session.compact === "function") {
+    await client.session.compact(body);
+    return "compact";
+  }
+  if (typeof client.session.summarize === "function") {
+    await client.session.summarize(body);
+    return "summarize";
+  }
+  throw new Error("session.compact and session.summarize are unavailable");
+}
+
+export default async function loopAgentContextOverflowCompactPlugin({ client, $ }) {
+  void $;
+  void PLUGIN_PATH;
+
+  async function promptDeferredResume(sessionId, idleConfirmed = false) {
+    const deferred = deferredResume.get(sessionId);
+    if (!deferred) return;
+
+    if (!idleConfirmed) {
+      const status = await readSessionStatus(client, sessionId);
+      if (deferredResume.get(sessionId) !== deferred) return;
+      if (!status.ok || status.type !== "idle") return;
+    }
+
+    // An explicit idle event is authoritative even if the SDK status snapshot
+    // still lags at busy. Keep deferred facts until promptAsync is accepted so
+    // later idle can retry without another compact/summarize.
+    const prompt = buildOverflowResumePrompt(sessionId, deferred.error, deferred.attempt);
+    let response;
+    try {
+      response = await client.session.promptAsync({
+        path: { id: sessionId },
+        body: { parts: [{ type: "text", text: prompt }] },
+        throwOnError: true,
+      });
+    } catch {
+      return;
+    }
+    if (deferredResume.get(sessionId) !== deferred) return;
+    if (!promptWasAccepted(response)) return;
+    deferredResume.delete(sessionId);
+    getState(sessionId).deferredIdleConfirmed = false;
+  }
+
+  async function drainPendingOverflow(sessionId) {
+    const state = getState(sessionId);
+    // Deferred resume path: only promptAsync, never compact/summarize again.
+    if (deferredResume.has(sessionId)) {
+      const idleConfirmed = state.deferredIdleConfirmed;
+      state.deferredIdleConfirmed = false;
+      await promptDeferredResume(sessionId, idleConfirmed);
+      return;
+    }
+
+    const pending = pendingOverflow.get(sessionId);
+    if (!pending) return;
+    if (state.attempt >= MAX_OVERFLOW_RECOVERIES) {
+      pendingOverflow.delete(sessionId);
+      return;
+    }
+
+    const before = await readSessionStatus(client, sessionId);
+    if (pendingOverflow.get(sessionId) !== pending) return;
+    if (!before.ok || before.type !== "idle") return;
+
+    try {
+      await compactOrSummarize(client, sessionId);
+    } catch {
+      // Compact itself failed: do not consume budget (no compact side-effect yet).
+      return;
+    }
+    // Session cleanup may remove this work while compact is in flight. Do not
+    // let that stale worker consume the reset budget or recreate deferred state.
+    // Concurrent overflow cannot replace pending because session.error preserves
+    // the first in-flight recovery facts below.
+    if (pendingOverflow.get(sessionId) !== pending) return;
+
+    // Consume budget immediately and exactly once after an active recovery's
+    // successful compact/summarize.
+    const nextAttempt = Math.min(state.attempt + 1, MAX_OVERFLOW_RECOVERIES);
+    state.attempt = nextAttempt;
+    pendingOverflow.delete(sessionId);
+    // Keep resume facts across temporary post-compact busy/unknown status.
+    deferredResume.set(sessionId, { error: pending.error, attempt: nextAttempt });
+    await promptDeferredResume(sessionId);
+  }
+
+  function startRecoveryWorker(sessionId, deferredIdleConfirmed = false) {
+    const state = getState(sessionId);
+    if (deferredIdleConfirmed && deferredResume.has(sessionId)) {
+      state.deferredIdleConfirmed = true;
+    }
+    if (recoveryWorkers.has(sessionId)) {
+      state.rerunRequested = true;
+      return;
+    }
+    state.locked = true;
+    state.rerunRequested = false;
+    const worker = drainPendingOverflow(sessionId)
+      .catch(() => {})
+      .finally(() => {
+        recoveryWorkers.delete(sessionId);
+        const rerun = state.rerunRequested;
+        state.rerunRequested = false;
+        state.locked = false;
+        if (rerun && (pendingOverflow.has(sessionId) || deferredResume.has(sessionId))) {
+          startRecoveryWorker(sessionId);
+        }
+      });
+    recoveryWorkers.set(sessionId, worker);
+  }
+
+  function clearSession(sessionId) {
+    pendingOverflow.delete(sessionId);
+    deferredResume.delete(sessionId);
+    sessionStatus.delete(sessionId);
+    const state = sessionState.get(sessionId);
+    if (state) {
+      state.attempt = 0;
+      state.rerunRequested = false;
+      state.deferredIdleConfirmed = false;
+      if (!recoveryWorkers.has(sessionId)) state.locked = false;
+    }
+  }
+
+  function hasWork(sessionId) {
+    return pendingOverflow.has(sessionId) || deferredResume.has(sessionId);
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (!event || typeof event !== "object") return;
+      const properties = event.properties || {};
+      const sessionId =
+        properties.sessionID || properties.sessionId || properties.id || properties.info?.id;
+
+      if (event.type === "session.status") {
+        const current = statusType(properties.status);
+        if (sessionId && current) sessionStatus.set(sessionId, current);
+        if (sessionId && current === "idle" && hasWork(sessionId)) {
+          startRecoveryWorker(sessionId, deferredResume.has(sessionId));
+        }
+        return;
+      }
+
+      if (event.type === "session.idle") {
+        if (sessionId) {
+          sessionStatus.set(sessionId, "idle");
+          if (hasWork(sessionId)) {
+            startRecoveryWorker(sessionId, deferredResume.has(sessionId));
+          }
+        }
+        return;
+      }
+
+      if (event.type === "session.deleted") {
+        if (sessionId) clearSession(sessionId);
+        return;
+      }
+
+      if (event.type === "message.updated") {
+        const info = properties.info;
+        if (
+          info?.role === "assistant" &&
+          info.sessionID &&
+          (info.status === undefined || info.status === "completed") &&
+          info.time?.completed != null &&
+          info.error == null
+        ) {
+          clearSession(info.sessionID);
+        }
+        return;
+      }
+
+      if (event.type === "session.error") {
+        if (!sessionId) return;
+        const error = properties.error || properties;
+        if (!isContextOverflow(error)) {
+          return;
+        }
+        if (getState(sessionId).attempt >= MAX_OVERFLOW_RECOVERIES) {
+          pendingOverflow.delete(sessionId);
+          return { interaction: "plugin-ignore-overflow-cap", reason: "plugin-ignore-overflow-cap" };
+        }
+        // Preserve the first overflow facts while compact or deferred resume is
+        // in flight. Concurrent overflow must not replace them or queue compact.
+        if (pendingOverflow.has(sessionId) || deferredResume.has(sessionId)) {
+          return { pending: true };
+        }
+        pendingOverflow.set(sessionId, { error });
+        startRecoveryWorker(sessionId);
+        return { pending: true };
+      }
+    },
+  };
+}
+`;
+}
+export async function installProjectOpenCodeOverflowCompactPlugin(input) {
+    return installGeneratedProjectFile({
+        repoRoot: input.repoRoot,
+        relativePath: OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH,
+        content: buildOpenCodeContextOverflowCompactPluginSource(),
+        onlyIfMissing: input.onlyIfMissing,
+    });
+}
+/**
+ * Project-level Pi extension: normalize overflow errorMessage so native Pi
+ * overflow → compact → retry can fire. Does not touch settings or model windows.
+ */
+export function buildPiContextOverflowExtensionSource() {
+    return `/**
+ * loop-agent Pi context overflow extension
+ * Path: ${PI_CONTEXT_OVERFLOW_EXTENSION_PATH}
+ *
+ * On assistant message_end, rewrite overflow errorMessage to start with
+ * "context_length_exceeded:" so Pi's native overflow recovery can run.
+ * Idempotent. Does not write user settings or model context windows.
+ */
+const EXTENSION_PATH = ${JSON.stringify(PI_CONTEXT_OVERFLOW_EXTENSION_PATH)};
+${buildGeneratedContextOverflowPatternSource()}
+const NORMALIZED_PREFIX = "context_length_exceeded:";
+
+function isOverflowMessage(text) {
+  if (typeof text !== "string" || !text) return false;
+  return OVERFLOW_PATTERN.test(text);
+}
+
+export default function loopAgentContextOverflowExtension(pi) {
+  void EXTENSION_PATH;
+  pi.on("message_end", (event) => {
+    const message = event && event.message;
+    if (!message || message.role !== "assistant") return;
+    const current = message.errorMessage;
+    if (typeof current !== "string" || !current) return;
+    if (current.startsWith(NORMALIZED_PREFIX) || /context_length_exceeded/i.test(current)) {
+      return;
+    }
+    if (!isOverflowMessage(current)) return;
+    return {
+      message: {
+        ...message,
+        errorMessage: NORMALIZED_PREFIX + " " + current,
+      },
+    };
+  });
+}
+`;
+}
+export async function installProjectPiContextOverflowExtension(input) {
+    return installGeneratedProjectFile({
+        repoRoot: input.repoRoot,
+        relativePath: PI_CONTEXT_OVERFLOW_EXTENSION_PATH,
+        content: buildPiContextOverflowExtensionSource(),
+        onlyIfMissing: input.onlyIfMissing,
+    });
+}
+/**
+ * Nested merge plan for the project-owned Pi settings surface. Existing values
+ * (including explicit disabled flags) always win over recommendations.
+ */
+export function planProjectPiSettingsMerge(existing) {
+    if (existing === undefined) {
+        return {
+            action: "write",
+            reason: "missing-file",
+            path: PI_PROJECT_SETTINGS_PATH,
+            next: {
+                retry: { ...PI_RECOMMENDED_RETRY, provider: { ...PI_RECOMMENDED_RETRY.provider } },
+                compaction: { ...PI_RECOMMENDED_COMPACTION },
+            },
+        };
+    }
+    if (!isRecord(existing)) {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: PI_PROJECT_SETTINGS_PATH,
+            message: "project .pi/settings.json root must be a JSON object",
+        };
+    }
+    const retryPlan = planPiRetryMerge(existing);
+    if (retryPlan.reason === "invalid-json") {
+        return { ...retryPlan, path: PI_PROJECT_SETTINGS_PATH };
+    }
+    const retryDisabled = retryPlan.reason === "enabled-false";
+    const next = retryPlan.next ? { ...retryPlan.next } : { ...existing };
+    const compaction = isRecord(next.compaction) ? { ...next.compaction } : {};
+    let changed = (!retryDisabled && retryPlan.action === "write") ||
+        !isRecord(next.compaction);
+    if (compaction.enabled === undefined) {
+        compaction.enabled = PI_RECOMMENDED_COMPACTION.enabled;
+        changed = true;
+    }
+    next.compaction = compaction;
+    if (changed) {
+        return {
+            action: "write",
+            reason: "missing-fields",
+            path: PI_PROJECT_SETTINGS_PATH,
+            next,
+        };
+    }
+    if (retryDisabled) {
+        return {
+            action: "report",
+            reason: "enabled-false",
+            path: PI_PROJECT_SETTINGS_PATH,
+            next,
+            message: "retry.enabled=false is preserved; compaction settings already require no migration",
+        };
+    }
+    return {
+        action: "noop",
+        reason: "matches",
+        path: PI_PROJECT_SETTINGS_PATH,
+        next,
+    };
+}
+async function readJsonMergeTarget(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, "utf-8"));
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return undefined;
+        if (error instanceof SyntaxError)
+            return "__invalid_json__";
+        throw error;
+    }
+}
+export async function inspectProjectPiSettings(input) {
+    const settingsPath = path.join(input.repoRoot, PI_PROJECT_SETTINGS_PATH);
+    const parsed = await readJsonMergeTarget(settingsPath);
+    if (parsed === "__invalid_json__") {
+        return { action: "report", reason: "invalid-json", path: PI_PROJECT_SETTINGS_PATH, wrote: false };
+    }
+    return { ...planProjectPiSettingsMerge(parsed), wrote: false };
+}
+export async function applyProjectPiSettingsMerge(input) {
+    const settingsPath = path.join(input.repoRoot, PI_PROJECT_SETTINGS_PATH);
+    const parsed = await readJsonMergeTarget(settingsPath);
+    if (parsed === "__invalid_json__") {
+        return { action: "report", reason: "invalid-json", path: PI_PROJECT_SETTINGS_PATH, wrote: false, message: "project .pi/settings.json is not valid JSON; refusing to write" };
+    }
+    const plan = planProjectPiSettingsMerge(parsed);
+    if (plan.action === "write" && plan.next) {
+        await writeJsonAtomic(settingsPath, plan.next);
+        return { ...plan, wrote: true };
+    }
+    return { ...plan, wrote: false };
+}
+export function buildProjectPiSettingsSource() {
+    return `${JSON.stringify({ retry: PI_RECOMMENDED_RETRY, compaction: PI_RECOMMENDED_COMPACTION }, null, 2)}\n`;
+}
+export async function inspectPiRetryConfig(input) {
+    const homeDir = input.homeDir ?? os.homedir();
+    const settingsPath = piSettingsPath(homeDir);
+    let raw;
+    try {
+        raw = await readFile(settingsPath, "utf-8");
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+        return {
+            action: "report",
+            reason: "missing-file",
+            path: settingsPath,
+            wrote: false,
+        };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            return {
+                action: "report",
+                reason: "invalid-json",
+                path: settingsPath,
+                wrote: false,
+            };
+        }
+        const plan = planPiRetryMerge(parsed);
+        return { ...plan, path: settingsPath, wrote: false };
+    }
+    catch {
+        return {
+            action: "report",
+            reason: "invalid-json",
+            path: settingsPath,
+            wrote: false,
+        };
+    }
+}
+function skippedInstall(relativePath) {
+    return { path: relativePath, written: false, reason: "skipped" };
+}
+/**
+ * Install project recovery artifacts and optionally merge Pi user settings.
+ * - auto/project: recovery plugins/extensions plus project `.pi/settings.json` (no home writes)
+ * - user: the same project files plus explicit legacy Pi home retry merge
+ * - off: skip all
+ */
+export async function runClientRecovery(input) {
+    const mode = input.mode ?? "auto";
+    if (mode === "off") {
+        return {
+            mode,
+            plugin: skippedInstall(OPENCODE_TRANSIENT_RETRY_PLUGIN_PATH),
+            overflowPlugin: skippedInstall(OPENCODE_CONTEXT_OVERFLOW_COMPACT_PLUGIN_PATH),
+            piExtension: skippedInstall(PI_CONTEXT_OVERFLOW_EXTENSION_PATH),
+            pi: { action: "report", reason: "skipped-mode", path: PI_PROJECT_SETTINGS_PATH, wrote: false },
+        };
+    }
+    const plugin = await installProjectOpenCodePlugin({
+        repoRoot: input.repoRoot,
+    });
+    const overflowPlugin = await installProjectOpenCodeOverflowCompactPlugin({
+        repoRoot: input.repoRoot,
+    });
+    const piExtension = await installProjectPiContextOverflowExtension({
+        repoRoot: input.repoRoot,
+    });
+    const pi = await applyProjectPiSettingsMerge({ repoRoot: input.repoRoot });
+    if (mode !== "user") {
+        return { mode, plugin, overflowPlugin, piExtension, pi };
+    }
+    const homeDir = input.homeDir ?? os.homedir();
+    const userPi = await applyPiRetryMerge({ homeDir });
+    return { mode, plugin, overflowPlugin, piExtension, pi, userPi };
+}