@supernova123/docker-mcp-server 0.3.1 → 0.3.2

package/dist/docker.d.ts

@@ -34,6 +34,16 @@ export declare function checkDockerConnection(docker: Dockerode): Promise<{
  * Returns structured error on timeout instead of hanging indefinitely.
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    label?: string;
+}): Promise<T>;
 export declare function formatError(error: unknown): string;
 export declare function formatContainer(container: Dockerode.ContainerInfo): Record<string, unknown>;
 export declare function formatImage(image: Dockerode.ImageInfo): Record<string, unknown>;

package/dist/docker.js

@@ -73,6 +73,85 @@ export async function withTimeout(promise, ms, label) {
         new Promise((_, reject) => setTimeout(() => reject(new DockerTimeoutError(`Docker API call "${label}" timed out after ${ms}ms`)), ms)),
     ]);
 }
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 1000, label = "Docker API call" } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Don't retry on non-transient errors
+            if (!isRetryableError(error)) {
+                throw error;
+            }
+            // Don't retry on last attempt
+            if (attempt === maxRetries) {
+                throw error;
+            }
+            // Exponential backoff: 1s, 2s, 4s
+            const delay = baseDelayMs * Math.pow(2, attempt);
+            process.stderr.write(`[retry] ${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms...\n`);
+            await new Promise(resolve => setTimeout(resolve, delay));
+        }
+    }
+    throw lastError;
+}
+/**
+ * Determine if an error is transient and worth retrying.
+ * Retries on: connection resets, timeouts, 5xx status codes.
+ * Does NOT retry on: 4xx (client errors), permission denied, not found.
+ */
+function isRetryableError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const msg = error.message.toLowerCase();
+    // Connection-level transient errors
+    if (msg.includes("econnreset") || msg.includes("econnrefused"))
+        return true;
+    if (msg.includes("etimedout") || msg.includes("socket hang up"))
+        return true;
+    if (msg.includes("epipe") || msg.includes("eai_again"))
+        return true;
+    // Docker API 5xx errors (server-side)
+    if (msg.includes("status code 5"))
+        return true;
+    if (msg.includes("internal server error"))
+        return true;
+    if (msg.includes("bad gateway"))
+        return true;
+    if (msg.includes("service unavailable"))
+        return true;
+    // Docker daemon busy (transient)
+    if (msg.includes("daemon is busy"))
+        return true;
+    if (msg.includes("too many requests"))
+        return true;
+    // 4xx errors are NOT retryable (client errors)
+    if (msg.includes("status code 4"))
+        return false;
+    if (msg.includes("not found"))
+        return false;
+    if (msg.includes("permission denied"))
+        return false;
+    if (msg.includes("bad request"))
+        return false;
+    // Permission/connection errors are NOT retryable
+    if (error.name === "DockerConnectionError")
+        return false;
+    if (error.name === "DockerPermissionError")
+        return false;
+    // Timeout errors ARE retryable (might be transient)
+    if (error.name === "DockerTimeoutError")
+        return true;
+    return false;
+}
 export function formatError(error) {
     if (error instanceof DockerConnectionError)
         return `${error.name}: ${error.message}`;

package/dist/server.js

@@ -11,7 +11,7 @@ import { registerMonitoringTools } from "./tools/monitoring.js";
 export function createServer(docker, options) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.3.1",
+        version: "0.3.2",
     });
     // Register all tool categories
     registerContainerTools(server, docker);

package/dist/tools/container.js

@@ -1,16 +1,16 @@
 import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, } from "../types.js";
-import { formatContainer, formatError } from "../docker.js";
+import { formatContainer, formatError, withRetry } from "../docker.js";
 export function registerContainerTools(server, docker) {
     server.tool("list_containers", "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.", ListContainersSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const containers = await docker.listContainers({
+            const containers = await withRetry(() => docker.listContainers({
                 all: params.all ?? false,
                 filters: JSON.stringify({
                     ...(params.label ? { label: params.label } : {}),
                     ...(params.name ? { name: [`/${params.name}`] } : {}),
                     ...(params.state ? { status: [params.state] } : {}),
                 }),
-            });
+            }), { label: "list_containers" });
             const results = containers.map(formatContainer);
             return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
         }
@@ -31,7 +31,7 @@ export function registerContainerTools(server, docker) {
     server.tool("start_container", "Start a stopped Docker container by ID or name.", StartContainerSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.start();
+            await withRetry(() => container.start(), { label: "start_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
         }
         catch (error) {
@@ -41,7 +41,7 @@ export function registerContainerTools(server, docker) {
     server.tool("stop_container", "Stop a running Docker container by ID or name with optional timeout.", StopContainerSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.stop({ t: params.timeout ?? 10 });
+            await withRetry(() => container.stop({ t: params.timeout ?? 10 }), { label: "stop_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
         }
         catch (error) {
@@ -55,7 +55,7 @@ export function registerContainerTools(server, docker) {
     server.tool("restart_container", "Restart a Docker container by ID or name with optional timeout. This tears down the running process and starts a new one — use stop_container for a graceful shutdown or remove_container to delete entirely. The timeout parameter (default 10s) controls how long to wait before force-killing. Returns a confirmation string on success. Idempotent: restarting an already-stopped container starts it again. Returns an error string if the container does not exist or is not running.", RestartContainerSchema.shape, { destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            await container.restart({ t: params.timeout ?? 10 });
+            await withRetry(() => container.restart({ t: params.timeout ?? 10 }), { label: "restart_container" });
             return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
         }
         catch (error) {

package/dist/tools/image.js

@@ -1,12 +1,12 @@
 import { ListImagesSchema, PullImageSchema, BuildImageSchema, RemoveImageSchema, } from "../types.js";
-import { formatImage, formatError } from "../docker.js";
+import { formatImage, formatError, withRetry } from "../docker.js";
 export function registerImageTools(server, docker) {
     server.tool("list_images", "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.", ListImagesSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const images = await docker.listImages({
+            const images = await withRetry(() => docker.listImages({
                 all: params.all ?? false,
                 filters: params.filter ? JSON.stringify({ reference: [params.filter] }) : undefined,
-            });
+            }), { label: "list_images" });
             const results = images.map(formatImage);
             return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
         }

package/dist/tools/logs.js

@@ -1,16 +1,16 @@
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
+import { formatError, sanitizeOutput, withRetry, formatBytes } from "../docker.js";
 export function registerLogsTools(server, docker) {
     server.tool("stream_logs", "Get logs from a single Docker container by ID or name. Use stream_logs for one container; use compose_logs for multi-service Compose stacks. Supports tail count (default 100 lines), since timestamp for filtering, and follow mode. Returns UTF-8 log text with multiplexed stream headers stripped, or 'No logs found.' when the container has no output. Read-only and safe to call repeatedly. Returns an error string if the container does not exist.", StreamLogsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
-            const logs = await container.logs({
+            const logs = await withRetry(() => container.logs({
                 stdout: true,
                 stderr: true,
                 tail: params.tail ?? 100,
                 since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
                 follow: false,
-            });
+            }), { label: "container_logs" });
             // Dockerode returns a Buffer with multiplexed stream headers
             // Use 100KB cap for logs to keep LLM context small
             const output = sanitizeOutput(logs.toString("utf-8"), 100_000);

package/dist/tools/network.js

@@ -1,11 +1,11 @@
 import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 export function registerNetworkTools(server, docker) {
     server.tool("list_networks", "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.", ListNetworksSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const networks = await docker.listNetworks({
+            const networks = await withRetry(() => docker.listNetworks({
                 filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
-            });
+            }), { label: "list_networks" });
             const results = networks.map((n) => ({
                 id: n.Id.substring(0, 12),
                 name: n.Name,

package/dist/tools/volume.js

@@ -1,14 +1,14 @@
 import { CreateVolumeSchema, InspectVolumeSchema, RemoveVolumeSchema, PruneVolumesSchema, } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 export function registerVolumeTools(server, docker) {
     server.tool("create_volume", "Create a Docker volume with optional driver, labels, and options. Returns volume name, driver, and mountpoint.", CreateVolumeSchema.shape, { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
-            const result = await docker.createVolume({
+            const result = await withRetry(() => docker.createVolume({
                 Name: params.name,
                 Driver: params.driver || "local",
                 Labels: params.labels,
                 DriverOpts: params.options,
-            });
+            }), { label: "create_volume" });
             return {
                 content: [{
                         type: "text",

package/dist/types.d.ts

@@ -5,15 +5,15 @@ export declare const ListContainersSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     state: z.ZodOptional<z.ZodEnum<["running", "stopped", "paused", "exited", "created", "restarting"]>>;
 }, "strip", z.ZodTypeAny, {
+    label?: string[] | undefined;
     name?: string | undefined;
     state?: "created" | "running" | "stopped" | "paused" | "exited" | "restarting" | undefined;
     all?: boolean | undefined;
-    label?: string[] | undefined;
 }, {
+    label?: string[] | undefined;
     name?: string | undefined;
     state?: "created" | "running" | "stopped" | "paused" | "exited" | "restarting" | undefined;
     all?: boolean | undefined;
-    label?: string[] | undefined;
 }>;
 export declare const InspectContainerSchema: z.ZodObject<{
     container_id: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "mcpName": "io.github.friendlygeorge/docker-mcp-server",
   "description": "MCP server for Docker — container management, health checks, auto-restart, Compose lifecycle, and log streaming for Claude, Cursor, and AI agents",
   "type": "module",

package/src/docker.ts

@@ -96,6 +96,88 @@ export async function withTimeout<T>(
   ]);
 }
 
+
+/**
+ * Retry a Docker API call with exponential backoff.
+ * Retries on transient errors (ECONNRESET, ETIMEDOUT, 5xx).
+ * Does NOT retry on 4xx errors (bad request, not found, permission denied).
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries?: number; baseDelayMs?: number; label?: string } = {}
+): Promise<T> {
+  const { maxRetries = 3, baseDelayMs = 1000, label = "Docker API call" } = options;
+  let lastError: unknown;
+  
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      // Don't retry on non-transient errors
+      if (!isRetryableError(error)) {
+        throw error;
+      }
+      
+      // Don't retry on last attempt
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Exponential backoff: 1s, 2s, 4s
+      const delay = baseDelayMs * Math.pow(2, attempt);
+      process.stderr.write(
+        `[retry] ${label} failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms...\n`
+      );
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Determine if an error is transient and worth retrying.
+ * Retries on: connection resets, timeouts, 5xx status codes.
+ * Does NOT retry on: 4xx (client errors), permission denied, not found.
+ */
+function isRetryableError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  
+  const msg = error.message.toLowerCase();
+  
+  // Connection-level transient errors
+  if (msg.includes("econnreset") || msg.includes("econnrefused")) return true;
+  if (msg.includes("etimedout") || msg.includes("socket hang up")) return true;
+  if (msg.includes("epipe") || msg.includes("eai_again")) return true;
+  
+  // Docker API 5xx errors (server-side)
+  if (msg.includes("status code 5")) return true;
+  if (msg.includes("internal server error")) return true;
+  if (msg.includes("bad gateway")) return true;
+  if (msg.includes("service unavailable")) return true;
+  
+  // Docker daemon busy (transient)
+  if (msg.includes("daemon is busy")) return true;
+  if (msg.includes("too many requests")) return true;
+  
+  // 4xx errors are NOT retryable (client errors)
+  if (msg.includes("status code 4")) return false;
+  if (msg.includes("not found")) return false;
+  if (msg.includes("permission denied")) return false;
+  if (msg.includes("bad request")) return false;
+  
+  // Permission/connection errors are NOT retryable
+  if (error.name === "DockerConnectionError") return false;
+  if (error.name === "DockerPermissionError") return false;
+  
+  // Timeout errors ARE retryable (might be transient)
+  if (error.name === "DockerTimeoutError") return true;
+  
+  return false;
+}
+
 export function formatError(error: unknown): string {
   if (error instanceof DockerConnectionError) return `${error.name}: ${error.message}`;
   if (error instanceof DockerTimeoutError) return `${error.name}: ${error.message}`;
@@ -164,4 +246,4 @@ export function formatBytes(bytes: number): string {
   const sizes = ["B", "KB", "MB", "GB", "TB"];
   const i = Math.floor(Math.log(bytes) / Math.log(k));
   return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
-}
+}

package/src/server.ts

@@ -17,7 +17,7 @@ export interface ServerOptions {
 export function createServer(docker: Dockerode, options?: ServerOptions): McpServer {
   const server = new McpServer({
     name: "docker-mcp-server",
-    version: "0.3.1",
+    version: "0.3.2",
   });
 
   // Register all tool categories

package/src/tools/container.ts

@@ -10,7 +10,7 @@ import {
   RecreateContainerSchema,
   RunContainerSchema,
 } from "../types.js";
-import { formatContainer, formatError } from "../docker.js";
+import { formatContainer, formatError, withRetry } from "../docker.js";
 
 export function registerContainerTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -20,14 +20,17 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const containers = await docker.listContainers({
-          all: params.all ?? false,
-          filters: JSON.stringify({
-            ...(params.label ? { label: params.label } : {}),
-            ...(params.name ? { name: [`/${params.name}`] } : {}),
-            ...(params.state ? { status: [params.state] } : {}),
+        const containers = await withRetry(
+          () => docker.listContainers({
+            all: params.all ?? false,
+            filters: JSON.stringify({
+              ...(params.label ? { label: params.label } : {}),
+              ...(params.name ? { name: [`/${params.name}`] } : {}),
+              ...(params.state ? { status: [params.state] } : {}),
+            }),
           }),
-        });
+          { label: "list_containers" }
+        );
         const results = containers.map(formatContainer);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
       } catch (error) {
@@ -60,7 +63,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.start();
+        await withRetry(() => container.start(), { label: "start_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} started.` }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
@@ -76,7 +79,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.stop({ t: params.timeout ?? 10 });
+        await withRetry(() => container.stop({ t: params.timeout ?? 10 }), { label: "stop_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} stopped.` }] };
       } catch (error: any) {
         // 304 means container is already stopped — treat as success
@@ -96,7 +99,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        await container.restart({ t: params.timeout ?? 10 });
+        await withRetry(() => container.restart({ t: params.timeout ?? 10 }), { label: "restart_container" });
         return { content: [{ type: "text", text: `Container ${params.container_id} restarted.` }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };

package/src/tools/health.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CheckHealthSchema, WatchHealthSchema, SetRestartPolicySchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerHealthTools(server: McpServer, docker: Dockerode): void {
   server.tool(

package/src/tools/image.ts

@@ -6,7 +6,7 @@ import {
   BuildImageSchema,
   RemoveImageSchema,
 } from "../types.js";
-import { formatImage, formatError } from "../docker.js";
+import { formatImage, formatError, withRetry } from "../docker.js";
 
 export function registerImageTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -16,10 +16,10 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const images = await docker.listImages({
+        const images = await withRetry(() => docker.listImages({
           all: params.all ?? false,
           filters: params.filter ? JSON.stringify({ reference: [params.filter] }) : undefined,
-        });
+        }), { label: "list_images" });
         const results = images.map(formatImage);
         return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
       } catch (error) {

package/src/tools/logs.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
+import { formatError, sanitizeOutput, withRetry, formatBytes } from "../docker.js";
 
 export function registerLogsTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -12,13 +12,13 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
-        const logs = await container.logs({
+        const logs = await withRetry(() => container.logs({
           stdout: true,
           stderr: true,
           tail: params.tail ?? 100,
           since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
           follow: false as const,
-        });
+        }), { label: "container_logs" });
         // Dockerode returns a Buffer with multiplexed stream headers
         // Use 100KB cap for logs to keep LLM context small
         const output = sanitizeOutput(logs.toString("utf-8"), 100_000);

package/src/tools/network.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerNetworkTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -11,9 +11,9 @@ export function registerNetworkTools(server: McpServer, docker: Dockerode): void
     { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const networks = await docker.listNetworks({
+        const networks = await withRetry(() => docker.listNetworks({
           filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
-        });
+        }), { label: "list_networks" });
         const results = networks.map((n) => ({
           id: n.Id.substring(0, 12),
           name: n.Name,

package/src/tools/volume.ts

@@ -6,7 +6,7 @@ import {
   RemoveVolumeSchema,
   PruneVolumesSchema,
 } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, withRetry } from "../docker.js";
 
 export function registerVolumeTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -16,12 +16,12 @@ export function registerVolumeTools(server: McpServer, docker: Dockerode): void
     { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
-        const result = await docker.createVolume({
+        const result = await withRetry(() => docker.createVolume({
           Name: params.name,
           Driver: params.driver || "local",
           Labels: params.labels,
           DriverOpts: params.options,
-        });
+        }), { label: "create_volume" });
         return {
           content: [{
             type: "text",
@@ -122,4 +122,4 @@ export function registerVolumeTools(server: McpServer, docker: Dockerode): void
       }
     }
   );
-}
+}

package/tests/retry.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi } from "vitest";
+import { withRetry, DockerTimeoutError, DockerConnectionError, DockerPermissionError } from "../src/docker.js";
+
+describe("withRetry", () => {
+  it("returns result on first attempt (no retry needed)", async () => {
+    const fn = vi.fn().mockResolvedValue("success");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("success");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on transient ECONNRESET error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("read ECONNRESET"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10, label: "test" });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("retries on timeout error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new DockerTimeoutError("timed out"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("does NOT retry on 404 Not Found", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("HTTP 404: Not Found"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("HTTP 404: Not Found");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on permission denied", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("Permission denied"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("Permission denied");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on DockerConnectionError", async () => {
+    const fn = vi.fn().mockRejectedValue(new DockerConnectionError("cannot connect"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("cannot connect");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retry on DockerPermissionError", async () => {
+    const fn = vi.fn().mockRejectedValue(new DockerPermissionError("access denied"));
+    await expect(withRetry(fn, { maxRetries: 3, baseDelayMs: 10 }))
+      .rejects.toThrow("access denied");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries on 500 Internal Server Error", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("HTTP 500: Internal Server Error"))
+      .mockResolvedValue("recovered");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("recovered");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("exhausts retries and throws last error", async () => {
+    const fn = vi.fn().mockRejectedValue(new Error("read ECONNRESET"));
+    await expect(withRetry(fn, { maxRetries: 2, baseDelayMs: 10 }))
+      .rejects.toThrow("read ECONNRESET");
+    expect(fn).toHaveBeenCalledTimes(3); // initial + 2 retries
+  });
+
+  it("retries on socket hang up", async () => {
+    const fn = vi.fn()
+      .mockRejectedValueOnce(new Error("socket hang up"))
+      .mockResolvedValue("ok");
+    const result = await withRetry(fn, { maxRetries: 3, baseDelayMs: 10 });
+    expect(result).toBe("ok");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});