@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.ts

@@ -40,30 +40,84 @@ import {
 
 const DEFAULT_RATE_LIMIT_BACKOFF_MS = 5 * 60 * 1000;
 const INVALID_REFRESH_TOKEN_BACKOFF_MS = 30 * 24 * 60 * 60 * 1000;
+// A sole/authed-but-cooling-down provider is worth sleeping out rather than failing the
+// turn (#123) -- but only up to a bound: INVALID_REFRESH_TOKEN_BACKOFF_MS (30 days) also
+// shows up as a "cooldown" on a subscription entry, and that one genuinely needs reauth,
+// not a wait. Cap at the same window as our own default rate-limit backoff.
+const SOLE_PROVIDER_MAX_WAIT_MS = DEFAULT_RATE_LIMIT_BACKOFF_MS;
+// Short in-place retry budget for a transient network/5xx blip on the SAME credential
+// (#122): a couple of quick retries, no cooldown, no rotation to another credential or
+// provider. Once this budget is exhausted the turn ends with an actionable error.
+const TRANSIENT_RETRY_BACKOFFS_MS = [250, 750];
 
 let runtimeContext: ExtensionContext | undefined;
 let extensionAPI: ExtensionAPI | undefined;
 
 type AttemptResult = {
-  result: "success" | "retry" | "fatal";
+  result: "success" | "rate_limited" | "fatal";
   retryAfterMs?: number;
   attemptAt: number;
+  classification?: ProviderErrorClassification;
 };
 
-function isFallbackLike(error: unknown): boolean {
+// #122/#124: a genuine rate limit (HTTP 429, or 503 WITH a real retry-after header) must
+// cool the credential down and rotate to the next one; a transient network/5xx blip
+// (connection reset, socket errors, timeouts, plain 500/502/504, or 503 with NO
+// retry-after) is not evidence the credential itself is bad -- it gets a short in-place
+// retry on the same credential, never a cooldown. Everything else is fatal. Bare
+// `usage`/`quota` substrings were dropped from the message match: they are false-positive
+// magnets (e.g. "usage" appears in normal assistant text) that used to cool down healthy
+// subscriptions for 5 minutes on any transient blip.
+type ProviderErrorClassification = {
+  kind: "rate_limit" | "transient" | "fatal";
+  status?: number;
+  reason: string;
+  hadRetryAfterHeader: boolean;
+};
+
+const TRANSIENT_MESSAGE_PATTERN =
+  /connection|network|fetch failed|socket|econnreset|econnrefused|enotfound|etimedout|timed? out|timeout|overloaded|service.?unavailable|temporarily unavailable/i;
+const RATE_LIMIT_MESSAGE_PATTERN = /\b429\b|rate.?limit|too many requests/i;
+// Precise terminal usage-limit signals (as opposed to the bare `usage`/`quota` substrings
+// dropped above): pi-ai's Codex adapter surfaces `usage_limit_reached` / `usage_not_included`
+// as the friendly "You have hit your ChatGPT usage limit..." message, often on a non-429
+// status, so the status-code check above misses it. These are specific enough not to false-
+// positive on ordinary assistant text mentioning "usage".
+const USAGE_LIMIT_MESSAGE_PATTERN = /usage[ _]limit|usage_not_included|usagelimiterror|insufficient_quota|quota exceeded/i;
+
+function classifyProviderError(error: unknown, observed: { status?: number; retryAfterMs?: number }): ProviderErrorClassification {
   const value = error as { status?: unknown; errorMessage?: unknown; message?: unknown } | undefined;
-  const status = typeof value?.status === "number" ? value.status : Number.NaN;
+  const errorStatus = typeof value?.status === "number" ? value.status : undefined;
+  const status = observed.status ?? errorStatus;
   const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : ""]
     .filter((part): part is string => typeof part === "string" && part.length > 0)
     .join(" ");
-  return (
-    status === 429 ||
-    status === 500 ||
-    status === 502 ||
-    status === 503 ||
-    status === 504 ||
-    /\b429\b|rate.?limit|too many requests|overloaded|service.?unavailable|temporarily unavailable|upstream|quota|usage|connection|network|fetch failed|socket|econnreset|econnrefused|enotfound|etimedout|timed? out|timeout|request was aborted/i.test(message)
-  );
+  const hadRetryAfterHeader = observed.retryAfterMs !== undefined;
+
+  if (status === 429) return { kind: "rate_limit", status, reason: "http 429", hadRetryAfterHeader };
+  if (status === 503 && hadRetryAfterHeader) return { kind: "rate_limit", status, reason: "http 503 with retry-after", hadRetryAfterHeader };
+  if (status === 500 || status === 502 || status === 503 || status === 504) {
+    return { kind: "transient", status, reason: `http ${status}`, hadRetryAfterHeader };
+  }
+  const transientMatch = message.match(TRANSIENT_MESSAGE_PATTERN);
+  if (transientMatch) return { kind: "transient", status, reason: transientMatch[0].toLowerCase(), hadRetryAfterHeader };
+  const rateLimitMatch = message.match(RATE_LIMIT_MESSAGE_PATTERN);
+  if (rateLimitMatch) return { kind: "rate_limit", status, reason: rateLimitMatch[0].toLowerCase(), hadRetryAfterHeader };
+  const usageLimitMatch = message.match(USAGE_LIMIT_MESSAGE_PATTERN);
+  if (usageLimitMatch) return { kind: "rate_limit", status, reason: usageLimitMatch[0].toLowerCase(), hadRetryAfterHeader };
+  return { kind: "fatal", status, reason: "unclassified", hadRetryAfterHeader };
+}
+
+async function defaultSleep(ms: number): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+// Indirection so tests can inject deterministic waits without real timers.
+let activeSleep: typeof defaultSleep = defaultSleep;
+
+/** Test-only seam: override the sleep implementation used for in-place/wait-out retries. Pass undefined to restore the default. */
+export function __setSleepForTest(fn: typeof defaultSleep | undefined): void {
+  activeSleep = fn ?? defaultSleep;
 }
 
 function isInvalidRefreshTokenError(error: unknown): boolean {
@@ -75,6 +129,27 @@ function isInvalidRefreshTokenError(error: unknown): boolean {
   return status === 400 && /invalid_grant|refresh token .*invalid|refresh token .*not found/i.test(message);
 }
 
+// A user/host abort (ESC, a critical-tier interrupt, a torn-down window) is NOT a provider
+// failure — it must never cool down a credential or rotate providers. The upstream pi-ai
+// providers set `reason: "aborted"` / `stopReason: "aborted"` (and throw "Request was aborted")
+// ONLY when the request's AbortSignal fired, so those markers alone are a reliable abort
+// signal; we do NOT require the signal to be threaded back through our own options (it may not
+// be), which is what made an ESC drain both provider pools.
+function isUserAbortEvent(event: Parameters<AssistantMessageEventStream["push"]>[0], signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  if (event.type !== "error") return false;
+  return event.reason === "aborted" || event.error.stopReason === "aborted" || /request was aborted/i.test(event.error.errorMessage ?? "");
+}
+
+function isUserAbortError(error: unknown, signal: AbortSignal | undefined): boolean {
+  if (signal?.aborted) return true;
+  const value = error as { name?: unknown; errorMessage?: unknown; message?: unknown } | undefined;
+  const message = [value?.errorMessage, value?.message, error instanceof Error ? error.message : String(error ?? "")]
+    .filter((part): part is string => typeof part === "string" && part.length > 0)
+    .join(" ");
+  return (error instanceof Error && /abort/i.test(error.name)) || /request was aborted|operation was aborted|the user aborted/i.test(message);
+}
+
 function setStatus(text: string): void {
   runtimeContext?.ui.setStatus("provider-rotation", text);
 }
@@ -209,6 +284,10 @@ export function __setStreamForProviderForTest(fn: typeof defaultStreamForProvide
   activeStreamForProvider = fn ?? defaultStreamForProvider;
 }
 
+// Drives ONE credential, retrying transient (non-rate-limit) failures in place on the
+// SAME credential per #122, and reports back a classified result for #124's logging.
+// A genuine rate limit ends the attempt immediately (the caller cools the credential down
+// and rotates); a transient blip gets a short in-place retry budget before giving up.
 async function streamProviderAttempt(
   providerId: ManagedProviderId,
   model: Model<any>,
@@ -217,84 +296,162 @@ async function streamProviderAttempt(
   credential: SubscriptionCredential,
   outer: AssistantMessageEventStream,
 ): Promise<AttemptResult> {
-  const attemptAt = Date.now();
-  markSubscriptionAttempt(providerId, credential.label, attemptAt);
-  let requestedRetryAfterMs: number | undefined;
-  const inner = streamForProvider(model, context, {
-    ...options,
-    apiKey: credential.access,
-    onResponse: async (response, responseModel) => {
-      if (response.status === 429 || response.status === 503) {
-        requestedRetryAfterMs = retryAfterMs(response.headers);
-      }
-      await options?.onResponse?.(response, responseModel);
-    },
-  });
+  for (let attempt = 1; ; attempt++) {
+    const attemptAt = Date.now();
+    markSubscriptionAttempt(providerId, credential.label, attemptAt);
+    let observedStatus: number | undefined;
+    let requestedRetryAfterMs: number | undefined;
+    const inner = streamForProvider(model, context, {
+      ...options,
+      apiKey: credential.access,
+      onResponse: async (response, responseModel) => {
+        observedStatus = response.status;
+        if (response.status === 429 || response.status === 503) {
+          requestedRetryAfterMs = retryAfterMs(response.headers);
+        }
+        await options?.onResponse?.(response, responseModel);
+      },
+    });
 
-  const bufferedEvents: Parameters<AssistantMessageEventStream["push"]>[0][] = [];
-  let sawContent = false;
+    const bufferedEvents: Parameters<AssistantMessageEventStream["push"]>[0][] = [];
+    let sawContent = false;
+    let classification: ProviderErrorClassification | undefined;
 
-  const flush = (): void => {
-    for (const event of bufferedEvents) outer.push(event);
-    bufferedEvents.length = 0;
-  };
+    const flush = (): void => {
+      for (const event of bufferedEvents) outer.push(event);
+      bufferedEvents.length = 0;
+    };
 
-  try {
-    for await (const event of inner) {
-      if (event.type === "error") {
-        if (isFallbackLike(event.error)) {
-          return { result: sawContent ? "fatal" : "retry", retryAfterMs: requestedRetryAfterMs, attemptAt };
+    try {
+      for await (const event of inner) {
+        if (event.type === "error") {
+          if (isUserAbortEvent(event, options?.signal)) {
+            bufferedEvents.push(event);
+            flush();
+            return { result: "fatal", attemptAt };
+          }
+          classification = classifyProviderError(event.error, { status: observedStatus, retryAfterMs: requestedRetryAfterMs });
+          if (classification.kind === "fatal" || sawContent) {
+            bufferedEvents.push(event);
+            flush();
+            return { result: "fatal", attemptAt, classification };
+          }
+          break;
         }
+        if (event.type !== "start" && event.type !== "done") sawContent = true;
         bufferedEvents.push(event);
+      }
+    } catch (error) {
+      if (isUserAbortError(error, options?.signal)) {
+        bufferedEvents.push({
+          type: "error",
+          reason: "aborted",
+          error: { ...toAssistantError(model, error instanceof Error ? error.message : String(error)), stopReason: "aborted" },
+        });
         flush();
         return { result: "fatal", attemptAt };
       }
-      if (event.type !== "start" && event.type !== "done") sawContent = true;
-      bufferedEvents.push(event);
+      classification = classifyProviderError(error, { status: observedStatus, retryAfterMs: requestedRetryAfterMs });
+      if (classification.kind === "fatal" || sawContent) {
+        bufferedEvents.push({
+          type: "error",
+          reason: "error",
+          error: toAssistantError(model, error instanceof Error ? error.message : String(error)),
+        });
+        flush();
+        return { result: "fatal", attemptAt, classification };
+      }
     }
-  } catch (error) {
-    if (isFallbackLike(error)) {
-      return { result: sawContent ? "fatal" : "retry", retryAfterMs: requestedRetryAfterMs, attemptAt };
+
+    if (!classification && requestedRetryAfterMs !== undefined && !sawContent) {
+      // Some providers signal a 429/503 purely via the response header without ever raising
+      // a stream "error" event; treat that the same as an explicit rate-limit classification.
+      classification = { kind: "rate_limit", status: observedStatus, reason: "retry-after header on success path", hadRetryAfterHeader: true };
+    }
+
+    if (!classification) {
+      flush();
+      return { result: "success", attemptAt };
     }
-    bufferedEvents.push({
-      type: "error",
-      reason: "error",
-      error: toAssistantError(model, error instanceof Error ? error.message : String(error)),
-    });
-    flush();
-    return { result: "fatal", attemptAt };
-  }
 
-  if (requestedRetryAfterMs !== undefined && !sawContent) {
-    return { result: "retry", retryAfterMs: requestedRetryAfterMs, attemptAt };
+    if (classification.kind === "rate_limit") {
+      return { result: "rate_limited", retryAfterMs: requestedRetryAfterMs, attemptAt, classification };
+    }
+
+    // Transient: retry the SAME credential/provider in place -- no cooldown, no rotation.
+    const backoffMs = TRANSIENT_RETRY_BACKOFFS_MS[attempt - 1];
+    if (backoffMs === undefined) {
+      // Exhausted the short in-place retry budget: surface a clear terminal error rather
+      // than spinning forever or silently rotating a healthy credential away.
+      bufferedEvents.push({
+        type: "error",
+        reason: "error",
+        error: toAssistantError(
+          model,
+          `${getProviderLabel(providerId)} "${credential.label}" hit a transient error after ${attempt} attempts (${classification.reason})`,
+        ),
+      });
+      flush();
+      return { result: "fatal", attemptAt, classification };
+    }
+    logRotation(
+      `${getProviderLabel(providerId)} subscription "${credential.label}" hit a transient error (${classification.reason}, status=${classification.status ?? "n/a"}); retrying same credential in ${backoffMs}ms (attempt ${attempt + 1})`,
+    );
+    await activeSleep(backoffMs);
   }
+}
 
-  flush();
-  return { result: "success", attemptAt };
+function emitTerminalError(stream: AssistantMessageEventStream, model: Model<any>, message: string): void {
+  stream.push({ type: "error", reason: "error", error: toAssistantError(model, message) });
+  stream.end();
+}
+
+// #123: gates cross-provider fallback on the target actually being usable right now --
+// authenticated (its subscription pool has at least one credential, even if currently
+// cooling down) AND registered in the model registry -- rather than blindly switching the
+// session model to a provider nobody logged into. Returns undefined when there is nothing
+// viable to switch to (config has no ladder rung, the target was already tried this turn,
+// the target has zero credentials, or its resolved model isn't in the registry).
+function resolveViableFallback(
+  providerId: ManagedProviderId,
+  modelId: string | undefined,
+  attempted: Set<ManagedProviderId>,
+): FallbackTarget | undefined {
+  const target = resolveFallbackTarget(providerId, modelId, readRotationConfig(), extensionAPI?.getThinkingLevel?.());
+  if (!target || attempted.has(target.providerId)) return undefined;
+  if (readSubscriptionPool(target.providerId).length === 0) return undefined;
+  if (!runtimeContext?.modelRegistry.find(target.providerId, target.modelId)) return undefined;
+  return target;
 }
 
-async function switchToFallbackModel(originalModel: { providerId: ManagedProviderId; modelId: string }): Promise<FallbackTarget> {
+// Switches the session model to an already-viability-checked fallback target. On the rare
+// race where the switch itself still fails (e.g. `setModel` rejects it), emits a graceful,
+// actionable terminal error on `stream` instead of throwing a generic "failed to switch".
+async function switchToFallbackModel(
+  stream: AssistantMessageEventStream,
+  model: Model<any>,
+  originalModel: { providerId: ManagedProviderId; modelId: string },
+): Promise<FallbackTarget | undefined> {
   const ctx = runtimeContext;
   if (!extensionAPI || !ctx) {
-    throw new Error(`Provider fallback unavailable: runtime not initialized for ${originalModel.providerId}/${originalModel.modelId}`);
+    emitTerminalError(stream, model, `Provider fallback unavailable: runtime not initialized for ${originalModel.providerId}/${originalModel.modelId}`);
+    return undefined;
   }
   const target = await switchToFallbackIfPossible(extensionAPI, ctx, originalModel);
   if (!target) {
-    const resolved = resolveFallbackTarget(originalModel.providerId, originalModel.modelId, readRotationConfig(), extensionAPI.getThinkingLevel?.());
-    throw new Error(`Provider fallback unavailable: failed to switch to ${resolved.label}`);
+    emitTerminalError(stream, model, `Provider fallback unavailable: failed to switch models for ${getProviderLabel(originalModel.providerId)}`);
+    return undefined;
   }
   return target;
 }
 
-function emitTerminalError(stream: AssistantMessageEventStream, model: Model<any>, message: string): void {
-  stream.push({ type: "error", reason: "error", error: toAssistantError(model, message) });
-  stream.end();
-}
-
 // Drives one managed provider's pool into `stream`; on exhaustion it switches the
 // session model to the cross-provider fallback and CONTINUES the same turn on it,
 // rather than failing the turn with an error. `attempted` guards anthropic<->codex
-// ping-pong: once both pools are dry we emit a single terminal error.
+// ping-pong: once both pools are dry (or unauthenticated) we emit a single terminal error.
+// If neither a fallback nor more credentials are available but the sole/current provider
+// is merely cooling down, we sleep out the shortest cooldown and retry it in place (#123)
+// instead of failing the turn.
 async function runManagedProvider(
   model: Model<any>,
   context: Context,
@@ -304,7 +461,8 @@ async function runManagedProvider(
 ): Promise<void> {
   const providerId = model.provider as ManagedProviderId;
   attempted.add(providerId);
-  const available = readSubscriptionPool(providerId).filter((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= Date.now());
+  const rawPool = readSubscriptionPool(providerId);
+  const available = rawPool.filter((entry) => !entry.rateLimitedUntil || entry.rateLimitedUntil <= Date.now());
 
   for (const credential of available) {
     let freshCredential: SubscriptionCredential;
@@ -344,39 +502,89 @@ async function runManagedProvider(
       return;
     }
 
-    if (result.result === "retry") {
+    if (result.result === "rate_limited") {
       const cooldownMs = result.retryAfterMs ?? DEFAULT_RATE_LIMIT_BACKOFF_MS;
       markSubscriptionRateLimited(providerId, freshCredential.label, cooldownMs, result.attemptAt);
-      logRotation(`${getProviderLabel(providerId)} subscription "${freshCredential.label}" cooled down for ${Math.ceil(cooldownMs / 1000)}s; trying next credential`);
+      // #124: make a misclassification obvious at a glance -- status, matched reason, and
+      // whether a real retry-after header drove the cooldown vs. our default backoff.
+      const retryAfterPart = result.retryAfterMs !== undefined ? `retry-after=${Math.ceil(result.retryAfterMs / 1000)}s` : "no retry-after header (default backoff)";
+      logRotation(
+        `${getProviderLabel(providerId)} subscription "${freshCredential.label}" rate-limited (status=${result.classification?.status ?? "n/a"}, reason=${result.classification?.reason ?? "unclassified"}, ${retryAfterPart}); cooling down for ${Math.ceil(cooldownMs / 1000)}s, trying next credential`,
+      );
       continue;
     }
 
     // Fatal (or partial content already streamed): cannot safely switch providers mid-turn.
+    if (result.classification) {
+      logRotation(
+        `${getProviderLabel(providerId)} subscription "${freshCredential.label}" failed fatally (status=${result.classification.status ?? "n/a"}, reason=${result.classification.reason})`,
+      );
+    }
     stream.end();
     return;
   }
 
-  // Pool exhausted — switch the session model to the fallback and continue this turn on it.
+  // Pool exhausted (or this provider was never authenticated at all) — figure out what to
+  // do next: switch to a viable cross-provider fallback, wait out a sole/authed provider's
+  // cooldown, or surface an actionable terminal error. Re-read the pool here rather than
+  // reusing the pre-loop `rawPool` snapshot: the credential loop above mutates cooldowns
+  // in place via `markSubscriptionRateLimited` (e.g. a sole credential that just got a
+  // fresh 429), and the stale snapshot would still show it as available, making the
+  // wait-out math below think there's nothing to wait for and wrongly declare exhaustion.
+  const currentPool = readSubscriptionPool(providerId);
   const originalModel = getCurrentModelRef(model);
   if (!originalModel) throw new Error(`Provider fallback unavailable: missing current model`);
 
-  const plannedTarget = resolveFallbackTarget(originalModel.providerId, originalModel.modelId, readRotationConfig(), extensionAPI?.getThinkingLevel?.());
-  if (attempted.has(plannedTarget.providerId)) {
-    emitTerminalError(stream, model, `All managed provider pools exhausted (tried ${[...attempted].join(", ")})`);
+  const viableTarget = resolveViableFallback(originalModel.providerId, originalModel.modelId, attempted);
+  if (viableTarget) {
+    const target = await switchToFallbackModel(stream, model, originalModel);
+    if (!target) return; // terminal error already emitted
+    logRotation(`${getProviderLabel(providerId)} pool exhausted -> ${target.label}`);
+    setStatus(`${getProviderLabel(providerId)} -> ${target.label}`);
+
+    const fallbackModel = runtimeContext?.modelRegistry.find(target.providerId, target.modelId);
+    if (!fallbackModel) {
+      emitTerminalError(stream, model, `Provider fallback unavailable: ${target.label} not in model registry`);
+      return;
+    }
+
+    await runManagedProvider(fallbackModel, context, options, stream, attempted);
     return;
   }
 
-  const target = await switchToFallbackModel(originalModel);
-  logRotation(`${getProviderLabel(providerId)} pool exhausted -> ${target.label}`);
-  setStatus(`${getProviderLabel(providerId)} -> ${target.label}`);
+  const label = getProviderLabel(providerId);
+  const triedList = [...attempted].join(", ");
 
-  const fallbackModel = runtimeContext?.modelRegistry.find(target.providerId, target.modelId);
-  if (!fallbackModel) {
-    emitTerminalError(stream, model, `Provider fallback unavailable: ${target.label} not in model registry`);
+  // #123: this provider was never authenticated at all (no subscription pool entries ever
+  // existed for it) -- there's nothing to wait out, so this is a config/setup problem, not
+  // a transient one.
+  if (currentPool.length === 0) {
+    emitTerminalError(stream, model, `${label} not authenticated — run \`crtr sys setup\` (or /provider-sub ${providerId} add) (tried ${triedList})`);
     return;
   }
 
-  await runManagedProvider(fallbackModel, context, options, stream, attempted);
+  // Authenticated but every credential is cooling down, and no authenticated fallback
+  // exists right now: sleep out the SHORTEST cooldown and retry the same provider instead
+  // of failing the turn -- this is the common "single subscription, briefly rate-limited"
+  // case, not a permanent outage.
+  const soonestRateLimitedUntil = Math.min(...currentPool.map((entry) => entry.rateLimitedUntil || 0));
+  const waitMs = soonestRateLimitedUntil - Date.now();
+
+  if (waitMs > 0 && waitMs <= SOLE_PROVIDER_MAX_WAIT_MS) {
+    logRotation(`${label} cooling down for ${Math.ceil(waitMs / 1000)}s with no authenticated fallback; waiting to retry the same provider`);
+    setStatus(`${label} cooling down for ${Math.ceil(waitMs / 1000)}s, retrying...`);
+    await activeSleep(waitMs);
+    await runManagedProvider(model, context, options, stream, attempted);
+    return;
+  }
+
+  emitTerminalError(
+    stream,
+    model,
+    waitMs > SOLE_PROVIDER_MAX_WAIT_MS
+      ? `${label} cooling down for ${Math.ceil(waitMs / 1000)}s — too long to wait automatically; authenticate a fallback provider with /provider-sub, or try again later (tried ${triedList})`
+      : `All managed provider pools exhausted (tried ${triedList})`,
+  );
 }
 
 function streamManagedProvider(model: Model<any>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream {

package/dist/builtin-pi-packages/pi-crtr-extensions/extensions/strip-skills-docs.ts

@@ -1,39 +1,46 @@
 /**
- * Strip pi-skill-system references from the system prompt
+ * Strip pi's "Pi documentation" block from the system prompt.
  *
- * Pi core hardcodes a "Pi documentation" block in its system prompt that maps
- * topics to doc files, including `skills (docs/skills.md)`, and lists "skills"
- * among the topics it covers. That mapping makes the agent extrapolate a
- * topic -> docs/<topic>.md pattern (e.g. a nonexistent docs/rules.md) and
- * surfaces pi's internal skill system when we don't want it referenced.
+ * Pi core hardcodes a "Pi documentation (read only when the user asks about pi
+ * itself, its SDK, extensions, themes, skills, or TUI):" block — a marker line
+ * plus a bullet list pointing at pi's README / docs / examples under
+ * node_modules. It causes two problems we fix by removing the whole block:
  *
- * This extension removes those references at runtime in `before_agent_start`,
- * so it survives `pi update` / `brew upgrade` (which would overwrite any edit
- * to the installed dist). It only touches the two skill references; everything
- * else in the block is left intact, and it degrades to a no-op if pi changes
- * the wording.
+ *  1. It maps topics to doc files (`skills (docs/skills.md)`, etc.), which makes
+ *     the agent extrapolate a topic -> docs/<topic>.md pattern and surface pi's
+ *     internal skill system when we don't want it referenced.
+ *  2. It is a THIRD-PARTY TELL. When authenticating a Claude subscription over
+ *     OAuth, Anthropic inspects the request and — if it doesn't look like genuine
+ *     Claude Code — routes it to "extra usage" instead of the plan, returning
+ *     HTTP 400 ("Third-party apps now draw from your extra usage..."). The
+ *     companion `pi-claude-oauth-adapter` normally strips this block for exactly
+ *     that reason, but it matches the marker string INCLUDING the word "skills,"
+ *     — and the earlier version of THIS extension mangled that marker (it removed
+ *     just the "skills" word), so the adapter's match failed and the block leaked
+ *     to the wire → every subscription turn 400'd. Removing the entire block here
+ *     is self-contained: it fixes the leak regardless of the adapter's marker,
+ *     load order, or presence, and subsumes the old skill-reference removal.
  *
- * Install: drop in ~/.pi/agent/extensions/ (global). Takes effect next session.
+ * Runs in `before_agent_start` so it survives `pi update` / `brew upgrade`
+ * (which would overwrite any edit to the installed dist), and degrades to a
+ * no-op if pi changes the wording.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-function stripSkillRefs(prompt: string): string {
-	if (!prompt.includes("docs/skills.md")) return prompt; // nothing to do / wording changed
-	let p = prompt;
-	// 1. The topic -> doc mapping entry, with surrounding comma cleanup so the
-	//    list reads cleanly whether the entry is mid-list or trailing.
-	p = p.replace(/,[ \t]*skills \(docs\/skills\.md\)/g, "");
-	p = p.replace(/skills \(docs\/skills\.md\)[ \t]*,[ \t]*/g, "");
-	// 2. The word "skills" in the "...asks about pi itself, its SDK, ... skills,
-	//    or TUI" enumeration.
-	p = p.replace(/,[ \t]*skills(?=[ \t]*,[ \t]*or TUI)/g, "");
-	return p;
+// Matches the whole block: the "Pi documentation (read only ...):" marker line
+// (with or without the "skills," enumeration) plus its trailing "- ..." bullets,
+// and any leading blank lines so the surrounding prompt closes up cleanly.
+const PI_DOCS_BLOCK = /\n*^Pi documentation \(read only[^\n]*:(?:\n[ \t]*-[^\n]*)*/m;
+
+function stripPiDocsBlock(prompt: string): string {
+	if (!prompt.includes("Pi documentation (read only")) return prompt; // no-op / wording changed
+	return prompt.replace(PI_DOCS_BLOCK, "").trimEnd() + "\n";
 }
 
 export default function stripSkillsDocs(pi: ExtensionAPI) {
 	pi.on("before_agent_start", async (event) => {
-		const stripped = stripSkillRefs(event.systemPrompt);
+		const stripped = stripPiDocsBlock(event.systemPrompt);
 		if (stripped === event.systemPrompt) return;
 		return { systemPrompt: stripped };
 	});