oira666_pi-limits-wait 0.5.2 → 0.5.3

package/src/settings.ts

@@ -1,130 +1,151 @@
-import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
-import { join, resolve } from "path";
-import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
-import { FALLBACK_MODELS_KEY, SETTINGS_FILE_NAME } from "./constants.js";
-import { formatModel, modelKey } from "./models.js";
-import { state } from "./state.js";
-import type { ConfiguredModel } from "./types.js";
-
-function isThinkingLevel(value: unknown): value is ModelThinkingLevel {
-  return ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(value));
-}
-
-export function parseConfiguredModels(raw: unknown): ConfiguredModel[] {
-  const source = raw && typeof raw === "object" && Array.isArray((raw as { [FALLBACK_MODELS_KEY]?: unknown })[FALLBACK_MODELS_KEY])
-    ? (raw as { [FALLBACK_MODELS_KEY]: unknown[] })[FALLBACK_MODELS_KEY]
-    : [];
-
-  const models: ConfiguredModel[] = [];
-  for (const item of source) {
-    if (!item || typeof item !== "object") continue;
-    const record = item as Record<string, unknown>;
-    const provider = typeof record.provider === "string" ? record.provider.trim() : "";
-    const modelname =
-      typeof record.modelname === "string" ? record.modelname.trim()
-      : typeof record.modelName === "string" ? record.modelName.trim()
-      : typeof record.model === "string" ? record.model.trim()
-      : "";
-    const reasoning = record["reasoning effort"] ?? record.reasoningEffort ?? record.reasoning_effort;
-    if (!provider || !modelname) continue;
-    models.push({ provider, modelname, reasoningEffort: isThinkingLevel(reasoning) ? reasoning : undefined });
-  }
-  return models;
-}
-
-export function configFileCandidates(cwd: string, agentDir = getAgentDir(), homeDir = homedir()): string[] {
-  return [
-    join(homeDir, ".config", ".pi", SETTINGS_FILE_NAME),
-    join(agentDir, SETTINGS_FILE_NAME),
-    resolve(cwd, `.${SETTINGS_FILE_NAME}`),
-    resolve(cwd, ".pi", SETTINGS_FILE_NAME),
-  ];
-}
-
-function mergeConfig(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
-  return { ...base, ...override };
-}
-
-export function readFallbackSettings(cwd: string, agentDir = getAgentDir(), homeDir = homedir()): { config: Record<string, unknown>; loadedPaths: string[]; warnings: string[] } {
-  let config: Record<string, unknown> = {};
-  const loadedPaths: string[] = [];
-  const warnings: string[] = [];
-  const seen = new Set<string>();
-
-  for (const candidate of configFileCandidates(cwd, agentDir, homeDir)) {
-    const path = resolve(candidate);
-    if (seen.has(path)) continue;
-    seen.add(path);
-    if (!existsSync(path)) continue;
-
-    try {
-      const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        warnings.push(`${path}: expected a JSON object`);
-        continue;
-      }
-      config = mergeConfig(config, parsed as Record<string, unknown>);
-      loadedPaths.push(path);
-    } catch (err) {
-      warnings.push(`${path}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  return { config, loadedPaths, warnings };
-}
-
-export function __readFallbackSettingsForTests(cwd: string, agentDir: string, homeDir: string): { config: Record<string, unknown>; loadedPaths: string[]; warnings: string[] } {
-  return readFallbackSettings(cwd, agentDir, homeDir);
-}
-
-export function loadFallbackSettings(ctx: ExtensionContext): void {
-  state.fallbackModels = [];
-
-  try {
-    const { config, loadedPaths, warnings } = readFallbackSettings(ctx.cwd);
-    const content = JSON.stringify({ config, loadedPaths, warnings });
-    const shouldNotify = state.settingsSignature !== content;
-    state.settingsSignature = content;
-
-    const configured = parseConfiguredModels(config);
-    if (configured.length === 0) {
-      if (shouldNotify && warnings.length > 0) ctx.ui.notify(`Could not fully load ${SETTINGS_FILE_NAME}: ${warnings.join(", ")}`, "warning");
-      return;
-    }
-
-    const modelWarnings: string[] = [];
-    const seen = new Set<string>();
-
-    for (const entry of configured) {
-      const model = ctx.modelRegistry.find(entry.provider, entry.modelname);
-      if (!model) {
-        modelWarnings.push(`missing ${entry.provider}/${entry.modelname}`);
-        continue;
-      }
-      if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
-        modelWarnings.push(`no auth ${entry.provider}/${entry.modelname}`);
-        continue;
-      }
-      const key = modelKey(model);
-      if (seen.has(key)) continue;
-      seen.add(key);
-      state.fallbackModels.push({ model, reasoningEffort: entry.reasoningEffort });
-    }
-
-    const lines = state.fallbackModels.map((entry, index) =>
-      `${index + 1}. ${formatModel(entry.model)}${entry.reasoningEffort ? ` (${entry.reasoningEffort})` : ""}`,
-    );
-    const source = loadedPaths.length > 0 ? ` from ${loadedPaths.join(", ")}` : "";
-    const message = lines.length > 0
-      ? `Loaded ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}${source}:\n${lines.join("\n")}`
-      : `Loaded ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}${source}, but no usable fallback models were found.`;
-    const allWarnings = [...warnings, ...modelWarnings];
-    if (shouldNotify) {
-      ctx.ui.notify(allWarnings.length > 0 ? `${message}\nSkipped: ${allWarnings.join(", ")}` : message, allWarnings.length > 0 ? "warning" : "info");
-    }
-  } catch (err) {
-    ctx.ui.notify(`Could not load ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}: ${err instanceof Error ? err.message : String(err)}`, "warning");
-  }
-}
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { getAgentDir, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ModelThinkingLevel } from "@earendil-works/pi-ai";
+import { FALLBACK_MODELS_KEY, SETTINGS_FILE_NAME } from "./constants.js";
+import { formatModel, modelKey } from "./models.js";
+import { state } from "./state.js";
+import type { ConfiguredModel } from "./types.js";
+
+function isThinkingLevel(value: unknown): value is ModelThinkingLevel {
+  return ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(value));
+}
+
+export function parseConfiguredModels(raw: unknown): ConfiguredModel[] {
+  const source = raw && typeof raw === "object" && Array.isArray((raw as { [FALLBACK_MODELS_KEY]?: unknown })[FALLBACK_MODELS_KEY])
+    ? (raw as { [FALLBACK_MODELS_KEY]: unknown[] })[FALLBACK_MODELS_KEY]
+    : [];
+
+  const models: ConfiguredModel[] = [];
+  for (const item of source) {
+    if (!item || typeof item !== "object") continue;
+    const record = item as Record<string, unknown>;
+    const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+    const modelname =
+      typeof record.modelname === "string" ? record.modelname.trim()
+      : typeof record.modelName === "string" ? record.modelName.trim()
+      : typeof record.model === "string" ? record.model.trim()
+      : "";
+    const reasoning = record["reasoning effort"] ?? record.reasoningEffort ?? record.reasoning_effort;
+    if (!provider || !modelname) continue;
+    models.push({ provider, modelname, reasoningEffort: isThinkingLevel(reasoning) ? reasoning : undefined });
+  }
+  return models;
+}
+
+export function configFileCandidates(
+  cwd: string,
+  agentDir = getAgentDir(),
+  homeDir = homedir(),
+  isProjectTrusted = false,
+): string[] {
+  const alwaysLoaded = [
+    join(homeDir, ".config", ".pi", SETTINGS_FILE_NAME),
+    join(agentDir, SETTINGS_FILE_NAME),
+  ];
+  return isProjectTrusted
+    ? [...alwaysLoaded, resolve(cwd, `.${SETTINGS_FILE_NAME}`), resolve(cwd, ".pi", SETTINGS_FILE_NAME)]
+    : alwaysLoaded;
+}
+
+function mergeConfig(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown> {
+  return { ...base, ...override };
+}
+
+export function readFallbackSettings(
+  cwd: string,
+  agentDir = getAgentDir(),
+  homeDir = homedir(),
+  isProjectTrusted = false,
+): { config: Record<string, unknown>; loadedPaths: string[]; warnings: string[] } {
+  let config: Record<string, unknown> = {};
+  const loadedPaths: string[] = [];
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+
+  for (const candidate of configFileCandidates(cwd, agentDir, homeDir, isProjectTrusted)) {
+    const path = resolve(candidate);
+    if (seen.has(path)) continue;
+    seen.add(path);
+    if (!existsSync(path)) continue;
+
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        warnings.push(`${path}: expected a JSON object`);
+        continue;
+      }
+      config = mergeConfig(config, parsed as Record<string, unknown>);
+      loadedPaths.push(path);
+    } catch (err) {
+      warnings.push(`${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { config, loadedPaths, warnings };
+}
+
+export function __readFallbackSettingsForTests(
+  cwd: string,
+  agentDir: string,
+  homeDir: string,
+  isProjectTrusted: boolean,
+): { config: Record<string, unknown>; loadedPaths: string[]; warnings: string[] } {
+  return readFallbackSettings(cwd, agentDir, homeDir, isProjectTrusted);
+}
+
+export function loadFallbackSettings(ctx: ExtensionContext): void {
+  state.fallbackModels = [];
+
+  try {
+    const { config, loadedPaths, warnings } = readFallbackSettings(
+      ctx.cwd,
+      getAgentDir(),
+      homedir(),
+      typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted(),
+    );
+    const content = JSON.stringify({ config, loadedPaths, warnings });
+    const shouldNotify = state.settingsSignature !== content;
+    state.settingsSignature = content;
+
+    const configured = parseConfiguredModels(config);
+    if (configured.length === 0) {
+      if (shouldNotify && warnings.length > 0) ctx.ui.notify(`Could not fully load ${SETTINGS_FILE_NAME}: ${warnings.join(", ")}`, "warning");
+      return;
+    }
+
+    const modelWarnings: string[] = [];
+    const seen = new Set<string>();
+
+    for (const entry of configured) {
+      const model = ctx.modelRegistry.find(entry.provider, entry.modelname);
+      if (!model) {
+        modelWarnings.push(`missing ${entry.provider}/${entry.modelname}`);
+        continue;
+      }
+      if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+        modelWarnings.push(`no auth ${entry.provider}/${entry.modelname}`);
+        continue;
+      }
+      const key = modelKey(model);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      state.fallbackModels.push({ model, reasoningEffort: entry.reasoningEffort });
+    }
+
+    const lines = state.fallbackModels.map((entry, index) =>
+      `${index + 1}. ${formatModel(entry.model)}${entry.reasoningEffort ? ` (${entry.reasoningEffort})` : ""}`,
+    );
+    const source = loadedPaths.length > 0 ? ` from ${loadedPaths.join(", ")}` : "";
+    const message = lines.length > 0
+      ? `Loaded ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}${source}:\n${lines.join("\n")}`
+      : `Loaded ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}${source}, but no usable fallback models were found.`;
+    const allWarnings = [...warnings, ...modelWarnings];
+    if (shouldNotify) {
+      ctx.ui.notify(allWarnings.length > 0 ? `${message}\nSkipped: ${allWarnings.join(", ")}` : message, allWarnings.length > 0 ? "warning" : "info");
+    }
+  } catch (err) {
+    ctx.ui.notify(`Could not load ${SETTINGS_FILE_NAME}.${FALLBACK_MODELS_KEY}: ${err instanceof Error ? err.message : String(err)}`, "warning");
+  }
+}

package/src/stream.ts

@@ -28,9 +28,10 @@ import {
 } from "./models.js";
 import { withAttemptResponseObserver } from "./response-observer.js";
 import { errorMessageWithCauses, getRetryableError, isAbortMessage, parseRetryDelayMs, retryAfterHeaderMs } from "./retry-errors.js";
+import type { RetryPeriodTracker } from "./retry-summary.js";
 import { loadFallbackSettings } from "./settings.js";
 import { state } from "./state.js";
-import type { FallbackModel, RetryableError, RuntimeStreamSimpleFn } from "./types.js";
+import type { FallbackModel, RetryReason, RetryableError, RuntimeStreamSimpleFn } from "./types.js";
 import { clearModelStatus, freezingEnabled, reasonLabel, waitForRetry } from "./ui.js";
 
 export function __setNonRetryableTuningForTests(maxAttempts: number, retryDelayMs: number): void {
@@ -168,6 +169,7 @@ export function streamWithLimitsRetry(
   context: Context,
   options?: ModelsSimpleStreamOptions,
   ownerSignal?: AbortSignal,
+  retryPeriod?: RetryPeriodTracker,
 ): AssistantMessageEventStream {
   const output = createAssistantMessageEventStream();
   const signal = options?.signal && ownerSignal
@@ -189,12 +191,22 @@ export function streamWithLimitsRetry(
     const nonRetryableAttempts = new Map<string, number>();
     const triedModels = new Set<string>();
 
+    const managedWait = async (reason: RetryReason, waitMs: number, error: string) =>
+      waitForRetry(reason, waitMs, signal, {
+        periodId: retryPeriod?.periodId,
+        model: attempt.model,
+        error,
+        events: retryPeriod?.events,
+        onEnd: (elapsedMs) => retryPeriod?.recordWait(elapsedMs),
+      });
+
     const flush = (buffer: AssistantMessageEvent[]) => {
       for (const event of buffer) output.push(event);
       committed = true;
     };
 
     const pushAbort = (message: string) => {
+      retryPeriod?.finalize();
       if (!committed) {
         output.push({ type: "start", partial: freshMessage(attempt.model) });
         committed = true;
@@ -281,8 +293,10 @@ export function streamWithLimitsRetry(
         await priorOnResponse?.(response, responseModel);
         if (signal?.aborted) return;
         // Throw only after the canonical callback, so after_provider_response
-        // still sees the response and 429 fallback can start immediately.
-        if (response.status === 429) throw new Error(observedHttpError);
+        // still sees every HTTP failure. All statuses remain retry eligible:
+        // classified failures use their normal policy and 400/403 deliberately
+        // enter the configured unknown-error retry loop.
+        if (response.status >= 400) throw new Error(observedHttpError);
       };
 
       try {
@@ -347,6 +361,7 @@ export function streamWithLimitsRetry(
                 output.push({ type: "start", partial: freshMessage(attempt.model) });
                 committed = true;
               }
+              if (event.type === "done") retryPeriod?.finalize();
               output.push(event);
               if (event.type === "done") {
                 finished = true;
@@ -356,6 +371,8 @@ export function streamWithLimitsRetry(
               continue;
             }
 
+            if (event.type === "error") retryPeriod?.recordReason(event.error.errorMessage ?? "Provider stream error");
+            if (event.type === "done" || event.type === "error") retryPeriod?.finalize();
             output.push(event);
             if (event.type === "done" || event.type === "error") {
               finished = true;
@@ -394,6 +411,8 @@ export function streamWithLimitsRetry(
         const failureEvent = nonRetryableError?.event;
         const failureMessage = nonRetryableError?.message ?? "Provider stream ended without a terminal event.";
         const emitFailure = () => {
+          retryPeriod?.recordReason(failureMessage);
+          retryPeriod?.finalize();
           if (!committed) {
             if (buffer.length > 0) flush(buffer);
             else {
@@ -417,10 +436,13 @@ export function streamWithLimitsRetry(
           nonRetryableAttempts.set(key, attempts);
           if (attempts < state.nonRetryableMaxAttempts) {
             notifyRetryingAfterError(attempt.model, state.nonRetryableRetryDelayMs, failureMessage);
-            if (await waitForRetry("retry", state.nonRetryableRetryDelayMs, signal) === "aborted") {
+            retryPeriod?.beginRetry(failureMessage);
+            const wait = await managedWait("retry", state.nonRetryableRetryDelayMs, failureMessage);
+            if (wait === "aborted" || signal?.aborted) {
               pushAbort("Request aborted while retrying after error.");
               return;
             }
+            retryPeriod?.completeRetry();
             continue;
           }
 
@@ -430,16 +452,19 @@ export function streamWithLimitsRetry(
               rememberNonRetryableFailure(attempt.model, failureMessage);
               const next = nextAvailableCandidate(attempt.model);
               if (next) {
+                retryPeriod?.recordImmediateRetry(failureMessage);
                 attempt = next;
                 continue;
               }
               const deadline = earliestCandidateDeadline(attempt.model);
               if (deadline) {
-                const wait = await waitForRetry("model-frozen", Math.max(0, deadline - Date.now()), signal);
-                if (wait === "aborted") {
+                retryPeriod?.beginRetry(failureMessage);
+                const wait = await managedWait("model-frozen", Math.max(0, deadline - Date.now()), failureMessage);
+                if (wait === "aborted" || signal?.aborted) {
                   pushAbort("Request aborted while all fallback models were frozen.");
                   return;
                 }
+                retryPeriod?.completeRetry();
                 attempt = nextAvailableCandidate(attempt.model)
                   ?? configuredAttempt(getPrimaryModel(attempt.model));
                 continue;
@@ -447,6 +472,7 @@ export function streamWithLimitsRetry(
             } else {
               const next = candidateOrder(attempt.model).find((entry) => !triedModels.has(modelKey(entry.model)));
               if (next) {
+                retryPeriod?.recordImmediateRetry(failureMessage);
                 attempt = next;
                 continue;
               }
@@ -460,37 +486,49 @@ export function streamWithLimitsRetry(
       if (allowFallback) {
         if (retryable.reason === "network") {
           notifyRetryableError(attempt.model, retryable, retryableErrorMessage);
-          if (await waitForRetry(retryable.reason, retryable.waitMs, signal) === "aborted") {
+          retryPeriod?.beginRetry(retryableErrorMessage);
+          const wait = await managedWait(retryable.reason, retryable.waitMs, retryableErrorMessage);
+          if (wait === "aborted" || signal?.aborted) {
             pushAbort(`Request aborted during ${reasonLabel(retryable.reason).toLowerCase()} wait.`);
             return;
           }
+          retryPeriod?.completeRetry();
           continue;
         }
 
         rememberRateLimit(attempt.model, retryable, retryableErrorMessage);
         const next = nextAvailableCandidate(attempt.model);
         if (next) {
+          retryPeriod?.recordImmediateRetry(retryableErrorMessage);
           attempt = next;
           continue;
         }
         const deadline = earliestCandidateDeadline(attempt.model);
         const waitMs = deadline ? Math.max(0, deadline - Date.now()) : retryable.waitMs;
-        if (await waitForRetry(retryable.reason, waitMs, signal) === "aborted") {
+        retryPeriod?.beginRetry(retryableErrorMessage);
+        const wait = await managedWait(retryable.reason, waitMs, retryableErrorMessage);
+        if (wait === "aborted" || signal?.aborted) {
           pushAbort(`Request aborted during ${reasonLabel(retryable.reason).toLowerCase()} wait.`);
           return;
         }
+        retryPeriod?.completeRetry();
         attempt = nextAvailableCandidate(attempt.model)
           ?? configuredAttempt(getPrimaryModel(attempt.model));
         continue;
       }
 
       notifyRetryableError(attempt.model, retryable, retryableErrorMessage);
-      if (await waitForRetry(retryable.reason, retryable.waitMs, signal) === "aborted") {
+      retryPeriod?.beginRetry(retryableErrorMessage);
+      const wait = await managedWait(retryable.reason, retryable.waitMs, retryableErrorMessage);
+      if (wait === "aborted" || signal?.aborted) {
         pushAbort(`Request aborted during ${reasonLabel(retryable.reason).toLowerCase()} wait.`);
         return;
       }
+      retryPeriod?.completeRetry();
     }
   })().catch((error) => {
+    retryPeriod?.recordReason(errorMessageWithCauses(error));
+    retryPeriod?.finalize();
     const failure = freshMessage(model);
     failure.stopReason = signal?.aborted ? "aborted" : "error";
     failure.errorMessage = errorMessageWithCauses(error);
@@ -526,23 +564,30 @@ interface InterceptionSlot {
 type InterceptablePrototype = ModelRuntime & { [INTERCEPTION_SYMBOL]?: InterceptionSlot };
 
 /** Install one stable, reload-safe process-wide trampoline. */
-export function installModelRuntimeInterception(): () => boolean {
+export function installModelRuntimeInterception(
+  createRetryPeriod?: () => RetryPeriodTracker,
+): () => boolean {
   const prototype = ModelRuntime.prototype as InterceptablePrototype;
   const owner = {};
   const controller = new AbortController();
   let slot = prototype[INTERCEPTION_SYMBOL];
 
-  const handler: InterceptionHandler = (runtime, model, context, options, delegate) =>
-    streamWithLimitsRetry(runtime, delegate, model, context, options, controller.signal);
+  const handler: InterceptionHandler = (runtime, model, context, options, delegate) => {
+    let retryPeriod: RetryPeriodTracker | undefined;
+    try { retryPeriod = createRetryPeriod?.(); } catch { /* summary tracking is observational */ }
+    return streamWithLimitsRetry(runtime, delegate, model, context, options, controller.signal, retryPeriod);
+  };
 
   if (slot && prototype.streamSimple === slot.wrapper) {
-    slot.abortOwner?.();
+    const previousAbort = slot.abortOwner;
     slot.owner = owner;
     slot.abortOwner = () => controller.abort();
     slot.handler = handler;
+    // Publish the new owner before abort telemetry can re-enter interception.
+    previousAbort?.();
   } else {
+    const previousAbort = slot?.abortOwner;
     if (slot) {
-      slot.abortOwner?.();
       slot.owner = undefined;
       slot.abortOwner = undefined;
       slot.handler = undefined;
@@ -565,14 +610,17 @@ export function installModelRuntimeInterception(): () => boolean {
       value: slot,
     });
     prototype.streamSimple = slot.wrapper;
+    previousAbort?.();
   }
 
   return () => {
     if (slot?.owner !== owner) return false;
-    slot.abortOwner?.();
+    const abortOwner = slot.abortOwner;
     slot.owner = undefined;
     slot.abortOwner = undefined;
     slot.handler = undefined;
-    return true;
+    abortOwner?.();
+    // A re-entrant install during abort owns the shared slot now.
+    return slot.owner === undefined;
   };
 }

package/src/telemetry.ts

@@ -0,0 +1,78 @@
+import type { EventBus } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { RetryReason } from "./types.js";
+
+/** Public, versioned pi.events channel for limits-wait wait telemetry. */
+export const LIMITS_WAIT_EVENT_CHANNEL = "oira666.pi-limits-wait.wait.v1";
+
+export type LimitsWaitModel = {
+  provider: string;
+  id: string;
+};
+
+export type LimitsWaitWaitOutcome = "waited" | "skipped" | "aborted";
+
+export type LimitsWaitWaitStartPayload = {
+  version: 1;
+  phase: "start";
+  waitId: string;
+  periodId?: string;
+  reason: RetryReason;
+  plannedDurationMs: number;
+  plannedDeadline: number;
+  startedAt: number;
+  model?: LimitsWaitModel;
+  error?: string;
+};
+
+export type LimitsWaitWaitEndPayload = {
+  version: 1;
+  phase: "end";
+  waitId: string;
+  periodId?: string;
+  reason: RetryReason;
+  plannedDurationMs: number;
+  plannedDeadline: number;
+  startedAt: number;
+  endedAt: number;
+  actualElapsedMs: number;
+  outcome: LimitsWaitWaitOutcome;
+  model?: LimitsWaitModel;
+  error?: string;
+};
+
+export type LimitsWaitWaitEventPayload = LimitsWaitWaitStartPayload | LimitsWaitWaitEndPayload;
+
+// Concise public aliases; the longer names remain descriptive and compatible.
+export type LimitsWaitStartEventPayload = LimitsWaitWaitStartPayload;
+export type LimitsWaitEndEventPayload = LimitsWaitWaitEndPayload;
+export type LimitsWaitEventPayload = LimitsWaitWaitEventPayload;
+export type LimitsWaitOutcome = LimitsWaitWaitOutcome;
+
+export type WaitTelemetryOptions = {
+  periodId?: string;
+  model?: Pick<Model<Api>, "provider" | "id">;
+  error?: string;
+  events?: EventBus;
+  onEnd?: (actualElapsedMs: number, outcome: LimitsWaitWaitOutcome) => void;
+};
+
+let nextWaitId = 0;
+
+export function createWaitId(): string {
+  nextWaitId = (nextWaitId + 1) % Number.MAX_SAFE_INTEGER;
+  return `wait-${Date.now().toString(36)}-${nextWaitId.toString(36)}`;
+}
+
+export function waitModel(model: WaitTelemetryOptions["model"]): LimitsWaitModel | undefined {
+  return model ? { provider: model.provider, id: model.id } : undefined;
+}
+
+/** Event listeners are observational and must never alter retry control flow. */
+export function emitWaitTelemetry(events: EventBus | undefined, payload: LimitsWaitWaitEventPayload): void {
+  try {
+    events?.emit(LIMITS_WAIT_EVENT_CHANNEL, payload);
+  } catch {
+    // Custom/test event buses may throw even though Pi's standard bus isolates listeners.
+  }
+}