@robin7331/papyrus-cli 0.1.5 → 0.1.6

package/README.md

@@ -207,8 +207,14 @@ papyrus ./docs --yes
 ## Notes
 
 - In `auto` mode without `--format`, the model returns structured JSON with `format` + `content`.
+- Single-file input now also shows a live worker lane (spinner in TTY) while conversion is running.
 - Folder input is scanned recursively for `.pdf` files and processed in parallel.
 - In folder mode, `--output` must be a directory path and mirrored subfolders are preserved.
+- OpenAI rate-limit (`429`) responses are retried automatically using `Retry-After` (when present) plus exponential backoff.
+- Rate-limit retry tuning is available via environment variables:
+  - `PAPYRUS_RATE_LIMIT_MAX_RETRIES` (default `8`)
+  - `PAPYRUS_RATE_LIMIT_BASE_DELAY_MS` (default `2000`)
+  - `PAPYRUS_RATE_LIMIT_MAX_DELAY_MS` (default `120000`)
 - For scanned PDFs, output quality depends on OCR quality from the model.
 
 ## Development

package/dist/cli.js

@@ -117,19 +117,52 @@ async function processSingleFile(inputPath, options, promptText) {
         throw new Error("Input file must have a .pdf extension.");
     }
     await ensureApiKey();
-    const result = await convertPdf({
-        inputPath,
-        model: options.model,
-        mode: options.mode,
-        format: options.format,
-        instructions: options.instructions,
-        promptText
-    });
-    const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
-    await mkdir(dirname(outputPath), { recursive: true });
-    await writeFile(outputPath, result.content, "utf8");
-    console.log(`Output (${result.format}) written to: ${outputPath}`);
-    return result.usage;
+    const startedAt = Date.now();
+    const displayInput = relative(process.cwd(), inputPath) || inputPath;
+    const workerDashboard = process.stdout.isTTY
+        ? new AsciiWorkerDashboard(1, 1)
+        : null;
+    workerDashboard?.setSummary(0, 0);
+    workerDashboard?.setWorkerRunning(0, displayInput);
+    if (!workerDashboard) {
+        console.log(`[worker-1] Running ${displayInput}`);
+    }
+    try {
+        const result = await convertPdf({
+            inputPath,
+            model: options.model,
+            mode: options.mode,
+            format: options.format,
+            instructions: options.instructions,
+            promptText
+        });
+        const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, result.content, "utf8");
+        if (workerDashboard) {
+            workerDashboard.setWorkerDone(0, displayInput, `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`);
+            workerDashboard.setSummary(1, 0);
+        }
+        else {
+            console.log(`[worker-1] Done ${displayInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`);
+        }
+        console.log(`Output (${result.format}) written to: ${outputPath}`);
+        return result.usage;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (workerDashboard) {
+            workerDashboard.setWorkerFailed(0, displayInput, `${truncate(message, 42)} (${formatDurationMs(Date.now() - startedAt)})`);
+            workerDashboard.setSummary(1, 1);
+        }
+        else {
+            console.error(`[worker-1] Failed ${displayInput}: ${message} (${formatDurationMs(Date.now() - startedAt)})`);
+        }
+        throw error;
+    }
+    finally {
+        workerDashboard?.stop();
+    }
 }
 async function processFolder(inputDir, options, promptText) {
     if (options.output && looksLikeFileOutput(options.output)) {

package/dist/openaiPdfToMarkdown.js

@@ -8,6 +8,9 @@ const AUTO_RESPONSE_SCHEMA = z.object({
     format: z.enum(["md", "txt"]),
     content: z.string().min(1)
 });
+const RATE_LIMIT_MAX_RETRIES = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_MAX_RETRIES", 8);
+const RATE_LIMIT_BASE_DELAY_MS = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_BASE_DELAY_MS", 2_000);
+const RATE_LIMIT_MAX_DELAY_MS = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_MAX_DELAY_MS", 120_000);
 export async function convertPdf(options) {
     const inputPath = resolve(options.inputPath);
     await access(inputPath);
@@ -16,17 +19,17 @@ export async function convertPdf(options) {
         throw new Error("OPENAI_API_KEY is not set.");
     }
     const client = new OpenAI({ apiKey });
-    const uploaded = await client.files.create({
+    const uploaded = await withRateLimitRetry("file upload", () => client.files.create({
         file: createReadStream(inputPath),
         purpose: "user_data"
-    });
+    }));
     const agent = new Agent({
         name: "PDF Converter",
         instructions: "You convert PDF files precisely according to the requested output format.",
         model: options.model
     });
     const promptText = buildPromptText(options);
-    const result = await run(agent, [
+    const result = await withRateLimitRetry("model run", () => run(agent, [
         {
             role: "user",
             content: [
@@ -40,7 +43,7 @@ export async function convertPdf(options) {
                 }
             ]
         }
-    ]);
+    ]));
     const rawOutput = (result.finalOutput ?? "").trim();
     if (!rawOutput) {
         throw new Error("No content returned by the API.");
@@ -142,3 +145,188 @@ function parseAutoResponse(rawOutput) {
     }
     return { format: validated.data.format, content };
 }
+async function withRateLimitRetry(operationName, operation) {
+    let attempt = 0;
+    while (true) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isRetriableRateLimitError(error) || attempt >= RATE_LIMIT_MAX_RETRIES) {
+                throw error;
+            }
+            const retryAfterMs = getRetryAfterMs(error);
+            const exponentialBackoffMs = RATE_LIMIT_BASE_DELAY_MS * (2 ** attempt);
+            const jitterMs = Math.floor(Math.random() * 750);
+            const computedDelayMs = retryAfterMs ?? (exponentialBackoffMs + jitterMs);
+            const waitMs = clampDelayMs(computedDelayMs, RATE_LIMIT_MAX_DELAY_MS);
+            const nextAttempt = attempt + 2;
+            const totalAttempts = RATE_LIMIT_MAX_RETRIES + 1;
+            const reason = extractErrorMessage(error);
+            console.warn(`[retry] ${operationName} hit OpenAI rate limits. Waiting ${formatDelay(waitMs)} before retry ${nextAttempt}/${totalAttempts}. ${reason}`);
+            await sleep(waitMs);
+            attempt += 1;
+        }
+    }
+}
+function isRetriableRateLimitError(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const candidate = error;
+    if (candidate.status === 429) {
+        const code = typeof candidate.code === "string" ? candidate.code : undefined;
+        const nestedCode = typeof candidate.error?.code === "string" ? candidate.error.code : undefined;
+        if (code === "insufficient_quota" || nestedCode === "insufficient_quota") {
+            return false;
+        }
+        return true;
+    }
+    const searchableText = [
+        toLowerCaseIfString(candidate.code),
+        toLowerCaseIfString(candidate.type),
+        toLowerCaseIfString(candidate.error?.code),
+        toLowerCaseIfString(candidate.error?.type),
+        toLowerCaseIfString(candidate.message),
+        toLowerCaseIfString(candidate.error?.message)
+    ]
+        .filter(Boolean)
+        .join(" ");
+    if (searchableText.includes("insufficient_quota")) {
+        return false;
+    }
+    return (searchableText.includes("rate_limit") ||
+        searchableText.includes("rate limit") ||
+        searchableText.includes("too many requests"));
+}
+function getRetryAfterMs(error) {
+    const headerDelay = getRetryAfterMsFromHeaders(error);
+    if (typeof headerDelay === "number" && Number.isFinite(headerDelay) && headerDelay >= 0) {
+        return headerDelay;
+    }
+    const textDelay = getRetryAfterMsFromText(extractErrorMessage(error));
+    if (typeof textDelay === "number" && Number.isFinite(textDelay) && textDelay >= 0) {
+        return textDelay;
+    }
+    return undefined;
+}
+function getRetryAfterMsFromHeaders(error) {
+    if (typeof error !== "object" || error === null) {
+        return undefined;
+    }
+    const candidate = error;
+    const retryAfterMsHeader = readHeader(candidate.headers, "retry-after-ms")
+        ?? readHeader(candidate.response?.headers, "retry-after-ms");
+    if (retryAfterMsHeader) {
+        const milliseconds = Number.parseInt(retryAfterMsHeader, 10);
+        if (Number.isFinite(milliseconds) && milliseconds >= 0) {
+            return milliseconds;
+        }
+    }
+    const retryAfterHeader = readHeader(candidate.headers, "retry-after")
+        ?? readHeader(candidate.response?.headers, "retry-after");
+    if (!retryAfterHeader) {
+        return undefined;
+    }
+    const seconds = Number.parseFloat(retryAfterHeader);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, Math.round(seconds * 1_000));
+    }
+    const parsedDate = Date.parse(retryAfterHeader);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(0, parsedDate - Date.now());
+    }
+    return undefined;
+}
+function getRetryAfterMsFromText(message) {
+    const match = message.match(/(?:try again in|retry after)\s*([0-9]+(?:\.[0-9]+)?)\s*(ms|msec|millisecond|milliseconds|s|sec|second|seconds|m|min|minute|minutes)?/i);
+    if (!match) {
+        return undefined;
+    }
+    const rawValue = Number.parseFloat(match[1] ?? "");
+    if (!Number.isFinite(rawValue) || rawValue < 0) {
+        return undefined;
+    }
+    const unit = (match[2] ?? "s").toLowerCase();
+    if (unit === "ms" || unit === "msec" || unit === "millisecond" || unit === "milliseconds") {
+        return Math.round(rawValue);
+    }
+    if (unit === "m" || unit === "min" || unit === "minute" || unit === "minutes") {
+        return Math.round(rawValue * 60_000);
+    }
+    return Math.round(rawValue * 1_000);
+}
+function readHeader(headersLike, headerName) {
+    if (!headersLike) {
+        return undefined;
+    }
+    if (typeof headersLike === "object"
+        && "get" in headersLike
+        && typeof headersLike.get === "function") {
+        const value = headersLike.get(headerName);
+        return value ?? undefined;
+    }
+    if (typeof headersLike !== "object") {
+        return undefined;
+    }
+    const headersRecord = headersLike;
+    const lowerTarget = headerName.toLowerCase();
+    for (const [key, value] of Object.entries(headersRecord)) {
+        if (key.toLowerCase() !== lowerTarget) {
+            continue;
+        }
+        if (typeof value === "string") {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            const first = value.find((entry) => typeof entry === "string");
+            return typeof first === "string" ? first : undefined;
+        }
+    }
+    return undefined;
+}
+function parsePositiveIntEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return fallback;
+    }
+    return parsed;
+}
+function clampDelayMs(value, max) {
+    return Math.max(250, Math.min(Math.round(value), max));
+}
+function formatDelay(milliseconds) {
+    if (milliseconds < 1_000) {
+        return `${milliseconds}ms`;
+    }
+    const seconds = milliseconds / 1_000;
+    return `${seconds.toFixed(seconds >= 10 ? 0 : 1)}s`;
+}
+function extractErrorMessage(error) {
+    if (error instanceof Error && error.message.trim().length > 0) {
+        return error.message;
+    }
+    if (typeof error === "object" && error !== null) {
+        const message = error.message;
+        if (typeof message === "string" && message.trim().length > 0) {
+            return message;
+        }
+        const nestedMessage = error.error?.message;
+        if (typeof nestedMessage === "string" && nestedMessage.trim().length > 0) {
+            return nestedMessage;
+        }
+    }
+    return String(error);
+}
+function toLowerCaseIfString(value) {
+    return typeof value === "string" ? value.toLowerCase() : "";
+}
+function sleep(milliseconds) {
+    return new Promise((resolveSleep) => {
+        setTimeout(resolveSleep, milliseconds);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robin7331/papyrus-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "description": "Convert PDF to markdown or text with the OpenAI Agents SDK",
   "repository": {
@@ -37,6 +37,7 @@
   },
   "dependencies": {
     "@openai/agents": "^0.5.3",
+    "@robin7331/papyrus-cli": "^0.1.4",
     "commander": "^14.0.0",
     "dotenv": "^17.3.1",
     "openai": "^6.7.0",

package/src/cli.ts

@@ -164,20 +164,66 @@ async function processSingleFile(
   }
 
   await ensureApiKey();
-  const result = await convertPdf({
-    inputPath,
-    model: options.model,
-    mode: options.mode,
-    format: options.format,
-    instructions: options.instructions,
-    promptText
-  });
+  const startedAt = Date.now();
+  const displayInput = relative(process.cwd(), inputPath) || inputPath;
+  const workerDashboard = process.stdout.isTTY
+    ? new AsciiWorkerDashboard(1, 1)
+    : null;
+  workerDashboard?.setSummary(0, 0);
+  workerDashboard?.setWorkerRunning(0, displayInput);
+
+  if (!workerDashboard) {
+    console.log(`[worker-1] Running ${displayInput}`);
+  }
+
+  try {
+    const result = await convertPdf({
+      inputPath,
+      model: options.model,
+      mode: options.mode,
+      format: options.format,
+      instructions: options.instructions,
+      promptText
+    });
 
-  const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
-  await mkdir(dirname(outputPath), { recursive: true });
-  await writeFile(outputPath, result.content, "utf8");
-  console.log(`Output (${result.format}) written to: ${outputPath}`);
-  return result.usage;
+    const outputPath = resolve(options.output ?? defaultOutputPath(inputPath, result.format));
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, result.content, "utf8");
+
+    if (workerDashboard) {
+      workerDashboard.setWorkerDone(
+        0,
+        displayInput,
+        `${result.format} in ${formatDurationMs(Date.now() - startedAt)}`
+      );
+      workerDashboard.setSummary(1, 0);
+    } else {
+      console.log(
+        `[worker-1] Done ${displayInput} -> ${outputPath} (${result.format}, ${formatDurationMs(Date.now() - startedAt)})`
+      );
+    }
+
+    console.log(`Output (${result.format}) written to: ${outputPath}`);
+    return result.usage;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (workerDashboard) {
+      workerDashboard.setWorkerFailed(
+        0,
+        displayInput,
+        `${truncate(message, 42)} (${formatDurationMs(Date.now() - startedAt)})`
+      );
+      workerDashboard.setSummary(1, 1);
+    } else {
+      console.error(
+        `[worker-1] Failed ${displayInput}: ${message} (${formatDurationMs(Date.now() - startedAt)})`
+      );
+    }
+
+    throw error;
+  } finally {
+    workerDashboard?.stop();
+  }
 }
 
 type FolderSummary = {

package/src/openaiPdfToMarkdown.ts

@@ -35,6 +35,10 @@ const AUTO_RESPONSE_SCHEMA = z.object({
   content: z.string().min(1)
 });
 
+const RATE_LIMIT_MAX_RETRIES = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_MAX_RETRIES", 8);
+const RATE_LIMIT_BASE_DELAY_MS = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_BASE_DELAY_MS", 2_000);
+const RATE_LIMIT_MAX_DELAY_MS = parsePositiveIntEnv("PAPYRUS_RATE_LIMIT_MAX_DELAY_MS", 120_000);
+
 export async function convertPdf(options: ConvertOptions): Promise<ConvertResult> {
   const inputPath = resolve(options.inputPath);
   await access(inputPath);
@@ -46,10 +50,12 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
 
   const client = new OpenAI({ apiKey });
 
-  const uploaded = await client.files.create({
-    file: createReadStream(inputPath),
-    purpose: "user_data"
-  });
+  const uploaded = await withRateLimitRetry("file upload", () =>
+    client.files.create({
+      file: createReadStream(inputPath),
+      purpose: "user_data"
+    })
+  );
 
   const agent = new Agent({
     name: "PDF Converter",
@@ -58,21 +64,23 @@ export async function convertPdf(options: ConvertOptions): Promise<ConvertResult
   });
 
   const promptText = buildPromptText(options);
-  const result = await run(agent, [
-    {
-      role: "user",
-      content: [
-        {
-          type: "input_text",
-          text: promptText
-        },
-        {
-          type: "input_file",
-          file: { id: uploaded.id }
-        }
-      ]
-    }
-  ]);
+  const result = await withRateLimitRetry("model run", () =>
+    run(agent, [
+      {
+        role: "user",
+        content: [
+          {
+            type: "input_text",
+            text: promptText
+          },
+          {
+            type: "input_file",
+            file: { id: uploaded.id }
+          }
+        ]
+      }
+    ])
+  );
 
   const rawOutput = (result.finalOutput ?? "").trim();
   if (!rawOutput) {
@@ -201,3 +209,249 @@ function parseAutoResponse(rawOutput: string): Omit<ConvertResult, "usage"> {
 
   return { format: validated.data.format, content };
 }
+
+async function withRateLimitRetry<T>(operationName: string, operation: () => Promise<T>): Promise<T> {
+  let attempt = 0;
+  while (true) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isRetriableRateLimitError(error) || attempt >= RATE_LIMIT_MAX_RETRIES) {
+        throw error;
+      }
+
+      const retryAfterMs = getRetryAfterMs(error);
+      const exponentialBackoffMs = RATE_LIMIT_BASE_DELAY_MS * (2 ** attempt);
+      const jitterMs = Math.floor(Math.random() * 750);
+      const computedDelayMs = retryAfterMs ?? (exponentialBackoffMs + jitterMs);
+      const waitMs = clampDelayMs(computedDelayMs, RATE_LIMIT_MAX_DELAY_MS);
+      const nextAttempt = attempt + 2;
+      const totalAttempts = RATE_LIMIT_MAX_RETRIES + 1;
+      const reason = extractErrorMessage(error);
+
+      console.warn(
+        `[retry] ${operationName} hit OpenAI rate limits. Waiting ${formatDelay(waitMs)} before retry ${nextAttempt}/${totalAttempts}. ${reason}`
+      );
+
+      await sleep(waitMs);
+      attempt += 1;
+    }
+  }
+}
+
+function isRetriableRateLimitError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+
+  const candidate = error as {
+    status?: unknown;
+    code?: unknown;
+    type?: unknown;
+    error?: { code?: unknown; type?: unknown; message?: unknown };
+    message?: unknown;
+  };
+
+  if (candidate.status === 429) {
+    const code = typeof candidate.code === "string" ? candidate.code : undefined;
+    const nestedCode = typeof candidate.error?.code === "string" ? candidate.error.code : undefined;
+    if (code === "insufficient_quota" || nestedCode === "insufficient_quota") {
+      return false;
+    }
+
+    return true;
+  }
+
+  const searchableText = [
+    toLowerCaseIfString(candidate.code),
+    toLowerCaseIfString(candidate.type),
+    toLowerCaseIfString(candidate.error?.code),
+    toLowerCaseIfString(candidate.error?.type),
+    toLowerCaseIfString(candidate.message),
+    toLowerCaseIfString(candidate.error?.message)
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  if (searchableText.includes("insufficient_quota")) {
+    return false;
+  }
+
+  return (
+    searchableText.includes("rate_limit") ||
+    searchableText.includes("rate limit") ||
+    searchableText.includes("too many requests")
+  );
+}
+
+function getRetryAfterMs(error: unknown): number | undefined {
+  const headerDelay = getRetryAfterMsFromHeaders(error);
+  if (typeof headerDelay === "number" && Number.isFinite(headerDelay) && headerDelay >= 0) {
+    return headerDelay;
+  }
+
+  const textDelay = getRetryAfterMsFromText(extractErrorMessage(error));
+  if (typeof textDelay === "number" && Number.isFinite(textDelay) && textDelay >= 0) {
+    return textDelay;
+  }
+
+  return undefined;
+}
+
+function getRetryAfterMsFromHeaders(error: unknown): number | undefined {
+  if (typeof error !== "object" || error === null) {
+    return undefined;
+  }
+
+  const candidate = error as {
+    headers?: unknown;
+    response?: { headers?: unknown };
+  };
+
+  const retryAfterMsHeader = readHeader(candidate.headers, "retry-after-ms")
+    ?? readHeader(candidate.response?.headers, "retry-after-ms");
+  if (retryAfterMsHeader) {
+    const milliseconds = Number.parseInt(retryAfterMsHeader, 10);
+    if (Number.isFinite(milliseconds) && milliseconds >= 0) {
+      return milliseconds;
+    }
+  }
+
+  const retryAfterHeader = readHeader(candidate.headers, "retry-after")
+    ?? readHeader(candidate.response?.headers, "retry-after");
+  if (!retryAfterHeader) {
+    return undefined;
+  }
+
+  const seconds = Number.parseFloat(retryAfterHeader);
+  if (Number.isFinite(seconds)) {
+    return Math.max(0, Math.round(seconds * 1_000));
+  }
+
+  const parsedDate = Date.parse(retryAfterHeader);
+  if (Number.isFinite(parsedDate)) {
+    return Math.max(0, parsedDate - Date.now());
+  }
+
+  return undefined;
+}
+
+function getRetryAfterMsFromText(message: string): number | undefined {
+  const match = message.match(
+    /(?:try again in|retry after)\s*([0-9]+(?:\.[0-9]+)?)\s*(ms|msec|millisecond|milliseconds|s|sec|second|seconds|m|min|minute|minutes)?/i
+  );
+  if (!match) {
+    return undefined;
+  }
+
+  const rawValue = Number.parseFloat(match[1] ?? "");
+  if (!Number.isFinite(rawValue) || rawValue < 0) {
+    return undefined;
+  }
+
+  const unit = (match[2] ?? "s").toLowerCase();
+  if (unit === "ms" || unit === "msec" || unit === "millisecond" || unit === "milliseconds") {
+    return Math.round(rawValue);
+  }
+
+  if (unit === "m" || unit === "min" || unit === "minute" || unit === "minutes") {
+    return Math.round(rawValue * 60_000);
+  }
+
+  return Math.round(rawValue * 1_000);
+}
+
+function readHeader(headersLike: unknown, headerName: string): string | undefined {
+  if (!headersLike) {
+    return undefined;
+  }
+
+  if (
+    typeof headersLike === "object"
+    && "get" in headersLike
+    && typeof (headersLike as { get?: unknown }).get === "function"
+  ) {
+    const value = (headersLike as { get: (name: string) => string | null }).get(headerName);
+    return value ?? undefined;
+  }
+
+  if (typeof headersLike !== "object") {
+    return undefined;
+  }
+
+  const headersRecord = headersLike as Record<string, unknown>;
+  const lowerTarget = headerName.toLowerCase();
+  for (const [key, value] of Object.entries(headersRecord)) {
+    if (key.toLowerCase() !== lowerTarget) {
+      continue;
+    }
+
+    if (typeof value === "string") {
+      return value;
+    }
+
+    if (Array.isArray(value)) {
+      const first = value.find((entry) => typeof entry === "string");
+      return typeof first === "string" ? first : undefined;
+    }
+  }
+
+  return undefined;
+}
+
+function parsePositiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return fallback;
+  }
+
+  return parsed;
+}
+
+function clampDelayMs(value: number, max: number): number {
+  return Math.max(250, Math.min(Math.round(value), max));
+}
+
+function formatDelay(milliseconds: number): string {
+  if (milliseconds < 1_000) {
+    return `${milliseconds}ms`;
+  }
+
+  const seconds = milliseconds / 1_000;
+  return `${seconds.toFixed(seconds >= 10 ? 0 : 1)}s`;
+}
+
+function extractErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message.trim().length > 0) {
+    return error.message;
+  }
+
+  if (typeof error === "object" && error !== null) {
+    const message = (error as { message?: unknown; error?: { message?: unknown } }).message;
+    if (typeof message === "string" && message.trim().length > 0) {
+      return message;
+    }
+
+    const nestedMessage = (error as { error?: { message?: unknown } }).error?.message;
+    if (typeof nestedMessage === "string" && nestedMessage.trim().length > 0) {
+      return nestedMessage;
+    }
+  }
+
+  return String(error);
+}
+
+function toLowerCaseIfString(value: unknown): string {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function sleep(milliseconds: number): Promise<void> {
+  return new Promise((resolveSleep) => {
+    setTimeout(resolveSleep, milliseconds);
+  });
+}